Storyblok MCP Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools are clearly distinct with specific resource-action pairs (e.g., create_story vs. update_story), but there is some potential confusion between similar retrieval tools like retrieve_single_activity and retrieve_multiple_activities, or between create_approval and create_release_approval. The descriptions help clarify, but the sheer number of tools creates some cognitive overlap.
Naming Consistency5/5
Naming is highly consistent throughout, following a clear verb_noun pattern (e.g., create_story, update_story, delete_story) with predictable variations for bulk operations (bulk_create_stories) and retrieval types (retrieve_single_*, retrieve_multiple_*, fetch_*). The pattern is maintained across all 160 tools without deviation.
Tool Count2/5
With 160 tools, the count is excessive for a single server, even for a comprehensive CMS like Storyblok. This volume will overwhelm agents, making tool selection difficult and inefficient. A more focused or modular approach would be more appropriate for the domain.
Completeness5/5
The tool set provides exhaustive coverage of the Storyblok domain, including full CRUD operations for stories, assets, components, spaces, workflows, releases, and more, plus advanced features like translations, backups, approvals, and validations. No obvious gaps are present; it supports complete lifecycle management.
Average 2.9/5 across 160 of 160 tools scored. Lowest: 1.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.

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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but fails completely. It doesn't indicate whether this is a mutating operation (implied by 'creates' but not confirmed), what permissions are required, whether it's idempotent, what happens on failure, or any rate limits. The description provides zero behavioral context beyond the basic action.
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 extremely concise - just one sentence with no wasted words. However, this brevity comes at the cost of being under-specified rather than efficiently informative. While front-loaded, it lacks the substance needed for a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is completely inadequate. It doesn't explain what gets created, what the parameters mean, what the tool returns, or any behavioral characteristics. This leaves the agent with insufficient information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 2 parameters (name, parent_id), the description provides no information about what these parameters mean, their format constraints, or how they affect the operation. The schema shows 'name' is required and 'parent_id' is optional with a default of null, but the description doesn't explain what a component folder name should be or what parent_id refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Creates a new component folder' is a tautology that essentially restates the tool name 'create_component_folder' without adding specificity. It doesn't distinguish this tool from sibling tools like 'create_asset_folder' or 'create_space', nor does it clarify what a 'component folder' is in this context beyond the obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides absolutely no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when this operation is appropriate, or how it differs from similar creation tools in the sibling list like 'create_asset_folder' or 'create_space'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'Deletes a release' implies a destructive mutation, but it doesn't specify if deletion is permanent, requires specific permissions, has side effects (e.g., cascading deletions), or what happens on success/failure. For a destructive tool with zero annotation coverage, this is a critical gap in transparency.
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 extremely concise ('Deletes a release.') with no wasted words, but this brevity leads to under-specification rather than effective communication. It's front-loaded but lacks necessary detail. While not verbose, it fails to provide essential information, making it inefficient in conveying tool functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/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, lack of annotations, no output schema, and 0% schema description coverage, the description is completely inadequate. It doesn't address behavioral risks, parameter meaning, return values, or usage context. For a deletion tool with significant complexity and safety implications, this description provides minimal helpful information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the input schema provides no parameter descriptions. The tool description adds no information about the 'release_id' parameter—it doesn't explain what a release ID is, its format, where to find it, or validation rules. With one required parameter and no semantic details in either schema or description, this fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Deletes a release' is a tautology that merely restates the tool name 'delete_release' without adding specificity. It doesn't clarify what a 'release' is in this context (e.g., software release, content release) or distinguish this tool from other deletion tools like delete_story or delete_asset. The purpose is minimally stated but lacks differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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. It doesn't mention prerequisites (e.g., needing a release_id), consequences of deletion (e.g., irreversible action), or when to choose this over other deletion tools like delete_story or delete_asset. The description offers no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it 'Updates an existing component folder', without explaining what 'update' entails (e.g., whether it modifies metadata, structure, or permissions), what permissions are required, whether changes are reversible, or what happens on success/failure. This is inadequate for a mutation tool with zero 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 a single, efficient sentence with zero wasted words. It's appropriately sized for a basic tool definition, though this conciseness comes at the cost of completeness. Every word earns its place by stating the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a mutation tool with 4 parameters), lack of annotations, 0% schema description coverage, and no output schema, the description is severely incomplete. It doesn't cover behavioral traits, parameter meanings, usage context, or expected outcomes, making it inadequate for safe and effective tool invocation by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 4 parameters have descriptions in the schema. The tool description provides no information about parameters beyond implying a 'folder_id' is needed for updating. It doesn't explain what 'name', 'parent_id', or 'space_id' do, their formats, or constraints, leaving the agent to guess based on titles alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Updates an existing component folder (component group)', which provides a clear verb ('Updates') and resource ('component folder/component group'). However, it doesn't distinguish this from sibling tools like 'update_component' or 'update_asset_folder', leaving the specific scope of what a 'component folder' is ambiguous relative to other folder types in the system.
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 doesn't mention prerequisites (e.g., needing an existing folder_id), exclusions, or comparisons to sibling tools like 'create_component_folder' or 'delete_component_folder'. The agent must infer usage solely from the tool name and schema.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Updates' via the 'Management API,' implying a mutation operation, but fails to describe critical traits like required permissions, whether changes are reversible, rate limits, or what the response looks like. For a mutation tool with 16 parameters and no annotation coverage, this is a significant gap in 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 a single, efficient sentence with no wasted words, making it appropriately sized and front-loaded. However, it's overly concise given the tool's complexity, as it omits necessary details that would help an agent understand and invoke the tool correctly.
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 the tool's complexity (16 parameters, mutation operation, no annotations, no output schema, and 0% schema description coverage), the description is incomplete. It doesn't explain what the tool returns, how to handle partial updates, or the meaning of parameters, leaving significant gaps for an agent to navigate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about parameters, while the input schema has 0% description coverage and 16 parameters (e.g., 'ai_translation_disabled,' 'billing_address'). With such low schema coverage and no parameter details in the description, the agent lacks essential semantic context for using the tool effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Updates an existing Storyblok space via the Management API,' which provides a clear verb ('Updates') and resource ('Storyblok space'), but it doesn't differentiate from sibling tools like 'update_space_role' or 'update_story' beyond specifying the resource type. It's vague about what aspects of the space are updated, lacking specificity compared to siblings.
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 offers no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing space ID), exclusions, or comparisons with tools like 'create_space' or 'delete_space.' Without such context, an agent must infer usage from the tool name alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation via the Storyblok Management API, implying it's a mutation that requires API access, but doesn't specify required permissions, rate limits, side effects (e.g., if changes affect existing users), or response format. For a mutation tool with 12 parameters, this is insufficient.
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 just one sentence: 'Updates a space role's configuration via the Storyblok Management API.' It's front-loaded with the core action and includes the API context, with zero wasted words. However, this conciseness comes at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters, mutation operation, no output schema, 0% schema coverage, and no annotations), the description is completely inadequate. It doesn't explain what a 'space role' is, what configuration aspects can be updated, required permissions, response format, or error handling. For such a rich tool, this minimal description fails to provide necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 12 parameters have descriptions in the schema. The tool description adds no information about what parameters like 'allowed_languages', 'field_permissions', or 'branch_ids' mean or how they affect the space role configuration. This leaves all parameters semantically undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Updates a space role's configuration' which provides a clear verb ('Updates') and resource ('space role's configuration'), making the purpose understandable. However, it doesn't differentiate this from sibling tools like 'update_space' or 'update_collaborator' that also update configurations of different resources, leaving room for confusion about scope.
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 doesn't mention prerequisites (e.g., needing a space_role_id), when not to use it, or how it differs from similar tools like 'create_space_role' or 'delete_space_role'. This lack of context makes it hard for an agent to choose correctly among siblings.
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 are provided, so the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't describe what happens during the update (e.g., whether it overwrites or merges fields, if it requires specific permissions, or what the response looks like). For a mutation tool with 7 parameters and no annotation coverage, this lack of behavioral detail is a significant gap.
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 a single, straightforward sentence with no wasted words. It's front-loaded with the core action ('Updates an existing task') and includes relevant context ('in a specified Storyblok space using the Management API'). However, it could be more structured by explicitly mentioning key parameters or usage scenarios, but as-is, it's efficiently concise.
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 the complexity (7 parameters, mutation operation, no annotations, no output schema), the description is incomplete. It doesn't explain what the tool returns, how errors are handled, or provide any context about the update process beyond the basic action. For a tool with significant parameter and behavioral implications, this minimal description is inadequate to guide an agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 7 parameters have descriptions in the schema. The tool description adds no information about any parameters—it doesn't mention 'task_id' (the only required parameter) or explain what fields like 'lambda_code' or 'user_dialog' represent. With high parameter count and zero coverage, the description fails to compensate, leaving parameters entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb ('Updates') and resource ('an existing task in a specified Storyblok space'), which provides a basic understanding of the tool's function. However, it lacks specificity about what aspects of a task can be updated and doesn't differentiate from sibling tools like 'update_story' or 'update_webhook' beyond the resource type. The mention of 'using the Management API' adds some context but doesn't enhance the core purpose clarity.
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 doesn't mention prerequisites (e.g., needing an existing task ID), exclusions, or comparisons to sibling tools like 'create_task' or 'delete_task'. The agent must infer usage from the tool name and parameters alone, which is insufficient for effective decision-making.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'move' implies mutation but doesn't clarify if this is destructive (e.g., overwrites), requires specific permissions, has rate limits, or what happens on failure (e.g., partial moves). The description lacks essential behavioral traits needed for safe invocation.
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 a single, clear sentence with no wasted words, making it appropriately concise. However, it's too brief to be fully helpful, bordering on under-specified rather than optimally structured. It earns a high score for efficiency but loses points for lacking necessary detail.
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 the complexity of a bulk mutation tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It fails to address behavioral risks, parameter details, or expected outcomes, leaving significant gaps for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter details. The description mentions 'multiple assets' and 'specified folder', hinting at 'ids' and 'asset_folder_id', but doesn't explain parameter meanings (e.g., what IDs refer to, folder constraints) or formats. It adds minimal value beyond the parameter names, insufficient for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('move') and resource ('multiple assets to a specified folder'), which is clear but basic. It doesn't differentiate from sibling tools like 'bulk_restore_assets' or 'delete_multiple_assets', leaving the specific use case ambiguous. The purpose is understandable but lacks specificity about what distinguishes this bulk operation from individual moves or other bulk operations.
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. It doesn't mention prerequisites (e.g., permissions), when not to use it (e.g., for single assets), or compare it to siblings like 'bulk_restore_assets' or 'update_asset'. The description is too minimal to offer any contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('publishes') but fails to describe critical traits: whether this is a destructive or safe operation, permission requirements, rate limits, error handling, or what 'publish' means in this context (e.g., making stories live, scheduling). This leaves significant gaps for a mutation 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 a single, efficient sentence with no wasted words. It's front-loaded and appropriately sized for the tool's apparent complexity, though this conciseness comes at the cost of detail.
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 the tool's complexity (a bulk mutation operation), lack of annotations, no output schema, and 0% schema description coverage, the description is incomplete. It fails to provide necessary context about behavior, parameters, or outcomes, making it inadequate for safe and effective use by an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'by ID' which hints at the 'story_ids' parameter, but doesn't explain the format, constraints, or valid values (e.g., are IDs strings, UUIDs?). With one parameter and no schema descriptions, this minimal addition is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Publishes multiple stories by ID' clearly states the action (publishes) and resource (stories), but it's vague about what 'publish' entails and doesn't differentiate from the sibling tool 'publish_story'. It distinguishes by scale (multiple vs. single) but lacks specificity about the operation's nature.
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 'publish_story' or 'bulk_update_stories'. The description implies bulk operation but doesn't specify prerequisites, constraints, or typical use cases, leaving the agent without contextual direction.
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 are provided, so the description carries full burden. It mentions debugging via fetch parameters but doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires specific permissions, what the output format is, or any rate limits. For a debugging tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that front-loads the core purpose. There's no wasted verbiage, making it appropriately concise. However, it could be more structured by explicitly separating purpose from parameters or usage context.
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 the complexity of a debugging tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what debugging entails, what results to expect, or how it differs from similar tools. This leaves the agent with insufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It vaguely references 'various fetch parameters' but only 'story_id' is documented in the schema. The description doesn't explain what 'story_id' represents, its format, or any additional parameters implied by 'various fetch parameters'. This fails to add meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool is for debugging access to a story, which provides a vague purpose. It mentions 'various fetch parameters' but doesn't specify what debugging entails or what resources are involved. While it distinguishes from siblings like 'get_story' by focusing on debugging rather than retrieval, the purpose remains somewhat ambiguous.
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 versus alternatives like 'get_story' or 'fetch_stories'. The description implies usage for debugging access issues but doesn't specify scenarios, prerequisites, or exclusions. This leaves the agent without clear direction on appropriate contexts.
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 are provided, so the description carries the full burden. It mentions 'non-paginated' and 'optional filtering', which are useful behavioral traits, but fails to disclose critical details like whether this is a read-only operation, potential rate limits, authentication needs, or what happens on errors. For a retrieval tool with zero annotation coverage, this leaves significant gaps.
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 a single, efficient sentence that is front-loaded with the core action. It avoids unnecessary words, though it could be slightly more informative without losing 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?
Given the complexity (a retrieval tool with 2 parameters), lack of annotations, 0% schema coverage, and no output schema, the description is incomplete. It doesn't explain return values, error handling, or parameter usage, leaving the agent under-informed for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter details. The description only vaguely mentions 'optional filtering' without explaining the two parameters ('search' and 'with_parent'), their purposes, formats, or how they interact. It adds minimal value beyond the schema, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb ('retrieves') and resource ('component folders'), which clarifies the basic action. However, it lacks specificity about what 'component folders' are in this context and doesn't distinguish this tool from similar siblings like 'retrieve_component_versions' or 'fetch_components', making it somewhat vague.
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 mentions 'optional filtering' but provides no guidance on when to use this tool versus alternatives like 'fetch_components' or 'retrieve_single_component_folder'. It doesn't specify use cases, prerequisites, or exclusions, leaving the agent with minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states what the tool does ('fetch') without any information about permissions required, rate limits, whether it's read-only or has side effects, error behavior, or return format. This is inadequate for a tool with 30 parameters.
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, well-structured sentence that efficiently communicates the core purpose. Every word earns its place with no redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (30 parameters, no schema descriptions, no annotations, no output schema), the description is severely incomplete. It doesn't explain what 'stories' are in Storyblok context, how filtering works, what pagination returns, or any behavioral aspects needed for proper tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (all parameters have only titles like 'By Ids'), and the description provides no parameter information beyond 'advanced filtering and pagination'. With 30 undocumented parameters, the description fails to compensate for the complete lack of schema documentation.
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 ('fetch') and resource ('stories from Storyblok'), and specifies 'multiple stories' to indicate bulk retrieval. However, it doesn't differentiate from sibling tools like 'get_story' (singular) or 'bulk_create_stories' (write operation), which would require explicit comparison for a perfect score.
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 mentions 'advanced filtering and pagination' which implies usage for complex queries, but provides no explicit guidance on when to use this tool versus alternatives like 'get_story' (singular fetch) or 'bulk_create_stories' (write operation). There are no when/when-not statements or named alternatives.
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 are provided, so the description carries full burden but offers minimal behavioral insight. It mentions retrieval but doesn't disclose critical traits like whether it's read-only, requires authentication, has rate limits, returns paginated results, or handles errors. This is inadequate for a tool with three parameters and no output schema.
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 a single, straightforward sentence with no wasted words, making it appropriately concise. However, it's front-loaded with basic information but lacks depth, which limits its effectiveness despite the efficient structure.
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 the complexity (3 parameters, 0% schema coverage, no output schema, no annotations), the description is incomplete. It doesn't explain parameter usage, return values, or behavioral aspects, leaving significant gaps for the agent to operate effectively in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the three parameters (datasource_id, datasource_slug, dimension). It doesn't explain their roles, relationships, or how they affect retrieval, failing to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('retrieves') and resource ('multiple datasource entries') with context ('from a specified Storyblok space'), which is clear but basic. It doesn't differentiate from sibling tools like 'retrieve_single_datasource_entry' or 'retrieve_multiple_datasources', leaving the scope vague regarding what 'multiple' entails or how it differs.
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. With siblings like 'retrieve_single_datasource_entry' and 'retrieve_multiple_datasources', the description lacks any indication of context, prerequisites, or exclusions, leaving the agent to infer usage based on tool names alone.
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 are provided, so the description carries full burden. It states it 'retrieves' via the Management API, implying a read-only operation, but doesn't disclose behavioral traits like whether it requires specific permissions, rate limits, pagination behavior, error handling, or what the return format looks like (since no output schema exists). The description is minimal and lacks critical operational context.
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 a single, efficient sentence with no wasted words. It's appropriately sized for a simple retrieval tool, though it could be more informative. The structure is front-loaded with the core action, but lacks elaboration that might be necessary given the complexity implied by sibling tools.
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 the tool's complexity (implied by sibling tools handling workflow stages), lack of annotations, 0% schema coverage, and no output schema, the description is incomplete. It doesn't explain what 'workflow stage changes' are, how results are returned, or any operational constraints. For a tool with two parameters and no structured documentation, this minimal description is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'space_id' implicitly via 'in a Storyblok space', but doesn't explain the 'with_story' parameter at all. The description adds minimal meaning beyond the schema, failing to clarify parameter purposes or usage, leaving two parameters inadequately documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Retrieves') and resource ('multiple workflow stage changes'), but is vague about scope and format. It mentions 'in a Storyblok space via the Management API' which adds some context, but doesn't specify what 'multiple' means (e.g., paginated list, filtered set) or how it differs from other retrieval tools like 'retrieve_single_workflow_stage' or 'retrieve_multiple_workflows'.
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. There are sibling tools like 'retrieve_single_workflow_stage' and 'retrieve_multiple_workflows', but the description doesn't explain when this tool is appropriate (e.g., for batch viewing stage changes vs. single instances) or any prerequisites. Usage is implied only by the tool name.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data, implying it's a read operation, but doesn't mention potential side effects, error handling, rate limits, or authentication requirements. This leaves significant gaps in understanding how the tool behaves in practice.
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 a single, straightforward sentence with no wasted words. It's front-loaded with the core action, making it easy to parse quickly, though it could be more informative without sacrificing brevity.
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 the complexity of a retrieval tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks details on parameters, return values, error conditions, and usage context, making it inadequate for an agent to use the tool effectively without additional guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema only provides a parameter name and type without meaning. The description adds no information about the 'datasource_entry_id' parameter, such as what it represents, where to find it, or valid ranges. This fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'retrieves' and resource 'a single datasource entry', which clarifies the basic action. However, it doesn't distinguish this tool from sibling tools like 'retrieve_multiple_datasource_entries' or 'get_story', leaving the scope vague regarding what makes this retrieval specific to datasource entries versus other resources.
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 mentions the Storyblok Management API but doesn't specify prerequisites, such as authentication or permissions, or differentiate it from similar tools like 'retrieve_single_datasource' or 'retrieve_multiple_datasource_entries'.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool updates metadata or settings, implying a mutation operation, but fails to disclose critical traits such as required permissions, whether changes are reversible, rate limits, or what the response looks like. For a mutation tool with 13 parameters, this is a significant gap in 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 concise, consisting of a single sentence that directly states the tool's purpose. There's no unnecessary verbiage, and it's front-loaded with the core action. However, its brevity contributes to underspecification rather than optimal clarity, slightly reducing its effectiveness.
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 the complexity of 13 parameters, 0% schema description coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain the return values, error conditions, or detailed usage context. For a mutation tool with many parameters, this leaves significant gaps that could hinder correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 13 parameters have descriptions in the schema. The description only vaguely mentions 'metadata or settings' without specifying which parameters correspond to what, such as alt for alternative text or expire_at for expiration dates. It adds minimal value beyond the schema's property names, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose as 'Update an existing asset's metadata or settings,' which clearly indicates a verb ('Update') and resource ('asset'). However, it's somewhat vague about what specific metadata or settings can be updated, and it doesn't distinguish this tool from other update-related siblings like update_asset_folder or update_story, which could lead to confusion in tool selection.
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 doesn't mention prerequisites (e.g., needing an existing asset), exclusions, or compare it to other tools like bulk_update_stories or update_asset_folder. This lack of context could make it difficult for an agent to choose the right tool in scenarios involving asset modifications.
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 are provided, so the description carries the full burden. It states 'Updates an existing component' which implies a mutation operation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, side effects, rate limits, or what happens to unspecified fields. This is inadequate for a mutation tool with 14 parameters.
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 a single, efficient sentence that gets straight to the point. It's front-loaded with the core action and avoids unnecessary words. However, it's overly concise given the tool's complexity, bordering on under-specification.
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 the tool's complexity (14 parameters, mutation operation, no annotations, no output schema, and 0% schema coverage), the description is incomplete. It doesn't compensate for the lack of structured data, leaving the agent with insufficient information to use the tool effectively beyond basic intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides only parameter names and types without meaning. The description adds minimal value by mentioning 'all supported fields', but doesn't explain what those fields are, their purposes, or constraints. For 14 parameters, this leaves significant gaps in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb ('Updates') and resource ('an existing component'), which provides a basic purpose. However, it's vague about what 'all supported fields' means and doesn't distinguish this tool from other update_* tools in the sibling list (like update_story, update_asset, etc.). It lacks specificity about the component's nature or domain.
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 doesn't mention prerequisites (e.g., needing the component ID), compare it to create_component or delete_component, or specify any context for usage. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but fails to disclose any behavioral traits. It doesn't mention required permissions, whether the update is reversible, rate limits, error conditions, or what happens to unspecified fields. This is inadequate for a mutation tool with 20 parameters.
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, efficient sentence with zero wasted words. It's appropriately sized for a basic purpose statement, though its brevity contributes to deficiencies in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (20 parameters, mutation operation, no annotations, no output schema, 0% schema coverage), the description is severely incomplete. It lacks behavioral context, parameter guidance, usage rules, and output information, making it inadequate for proper tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning all 20 parameters are undocumented in the schema. The description adds no parameter information beyond implying 'extension_id' is required and 'context' exists, failing to compensate for the massive coverage gap. This leaves the agent guessing about most parameters.
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 ('Updates') and resource ('an existing extension') with specific context ('organization or partner'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'create_extension' or 'delete_extension' beyond the basic verb difference, which prevents a perfect score.
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 minimal guidance by mentioning the context ('organization or partner'), but offers no explicit when-to-use rules, prerequisites, or alternatives. It doesn't clarify when to use this versus 'create_extension' or other update tools, leaving the agent with insufficient usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action ('Creates') without detailing side effects, permissions needed, rate limits, or response format. This is inadequate for a mutation tool with zero 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 a single, efficient sentence with no wasted words. It is front-loaded and directly states the tool's action, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a bulk creation tool with no annotations, 0% schema coverage, and no output schema, the description is severely incomplete. It lacks essential details on behavior, parameters, and outcomes, making it inadequate for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'stories' parameter beyond implying it's an array. It fails to specify what each story object should contain, such as required fields or structure, leaving parameters largely undocumented.
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 ('Creates') and resource ('multiple stories in Storyblok'), making the purpose specific and understandable. However, it does not explicitly differentiate from its sibling 'create_story' beyond the 'multiple' aspect, which is implied but not contrasted.
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 'create_story' or 'bulk_update_stories'. The description lacks context on prerequisites, such as required permissions or data format, leaving the agent without usage direction.
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 are provided, so the description carries full burden. It mentions 'completes the asset upload process,' which suggests a write operation, but fails to disclose behavioral traits such as required permissions, whether it's idempotent, error handling, or side effects. This leaves critical gaps for an agent to understand the tool's 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?
The description is a single, efficient sentence that front-loads the main action ('completes the asset upload process'). It avoids unnecessary words, but could be more structured by adding context or prerequisites. Overall, it's appropriately sized with zero waste.
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 no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what 'completes' entails, the return value, error conditions, or how it integrates with sibling tools like 'init_asset_upload.' For a tool that likely involves mutation and coordination, this leaves significant gaps 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 description coverage is 0%, with one parameter 'asset_id' undocumented in the schema. The description adds no meaning beyond the schema, as it doesn't explain what 'asset_id' is (e.g., an identifier from 'init_asset_upload') or its format. With low coverage, the description doesn't compensate, but since there's only one parameter, the baseline is adjusted to 3 for minimal viability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'completes the asset upload process after S3 upload,' which provides a clear verb ('completes') and resource ('asset upload process'), but it's somewhat vague about what 'completes' entails (e.g., finalizing metadata, triggering processing). It doesn't differentiate from sibling tools like 'init_asset_upload' or 'update_asset,' leaving ambiguity in scope.
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 implies usage after an S3 upload, but it lacks explicit guidance on when to use this tool versus alternatives (e.g., 'init_asset_upload' for starting the process) or prerequisites. No exclusions or specific contexts are mentioned, making it insufficient for informed tool selection.
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 are provided, so the description carries the full burden. It mentions the Storyblok Management API but fails to disclose critical behavioral traits: this is a destructive operation (implied by 'Deletes'), it likely requires specific permissions, and there's no information on error handling, confirmation steps, or what happens upon success (e.g., if the role is permanently removed).
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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to scan quickly.
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 the complexity (a destructive operation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It lacks essential details: no explanation of parameters, behavioral risks, usage context, or expected outcomes, leaving significant gaps for an AI agent to operate safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, with one parameter ('space_role_id') undocumented in the schema. The description adds no meaning beyond the schema—it doesn't explain what a 'space_role_id' is, how to obtain it, or its format (e.g., integer ID from 'fetch_space_roles'). This fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Deletes') and resource ('a space role'), which provides a basic purpose. However, it's vague about what a 'space role' entails and doesn't differentiate from sibling tools like 'delete_collaborator' or 'delete_workflow_stage', which might involve similar deletion operations in the same system.
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. It doesn't mention prerequisites (e.g., needing a specific space role ID from 'fetch_space_roles'), exclusions, or related tools like 'update_space_role' or 'create_space_role' for context.
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 are provided, so the description carries the full burden of behavioral disclosure. It states 'Gets a specific component by ID,' which implies a read-only operation, but doesn't clarify critical aspects like authentication requirements, error handling (e.g., what happens if the ID is invalid), rate limits, or the format of the returned data. For a tool with no annotation coverage, this leaves significant gaps in understanding its 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, clear sentence with no wasted words: 'Gets a specific component by ID.' It is front-loaded with the core action and resource, making it easy to parse quickly. Every part of the sentence contributes directly to understanding the tool's function, achieving optimal 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?
Given the complexity (a read operation with one parameter), lack of annotations, no output schema, and low schema description coverage (0%), the description is incomplete. It doesn't explain what a 'component' entails, how results are returned, or behavioral traits like error cases. For a tool in a server with many siblings, more context is needed to ensure correct usage without relying on external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('id') with 0% description coverage, meaning the schema provides no details about the parameter. The description adds minimal semantics by implying the 'id' is used to retrieve a component, but it doesn't specify the ID format (e.g., numeric, UUID), source, or constraints. With low schema coverage, the description fails to compensate adequately, leaving the parameter poorly documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Gets a specific component by ID' clearly states the verb ('Gets') and resource ('component'), making the purpose understandable. However, it lacks specificity about what a 'component' is in this context (e.g., UI component, data component) and doesn't distinguish it from similar sibling tools like 'fetch_components' (which likely lists multiple components) or 'retrieve_single_component_version' (which might get versioned components). This makes it vague compared to alternatives.
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 doesn't mention prerequisites (e.g., needing a valid component ID), exclusions, or comparisons to sibling tools like 'fetch_components' (for listing) or 'get_component_usage' (for usage data). Without such context, an agent must infer usage from the tool name alone, which is insufficient for optimal selection.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions 'paginated versions', hinting at pagination behavior, but fails to detail critical aspects such as rate limits, authentication requirements, error handling, or what the output looks like (e.g., format, fields). For a read operation with no annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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, efficient sentence with no wasted words. It is appropriately sized for a simple tool and front-loaded with the core action ('retrieves paginated versions of a component'). Every word earns its place, making it highly concise and well-structured.
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 the tool's complexity (3 parameters, no output schema, no annotations), the description is incomplete. It lacks details on parameter semantics, behavioral traits, and output format. While it states the purpose concisely, it does not compensate for the missing structured data, making it insufficient for an agent to fully understand and correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter details. The description does not add any meaning beyond what the schema's property names imply (e.g., 'component_id', 'page', 'per_page'). It fails to explain what these parameters do, their constraints, or examples of usage, leaving all three parameters inadequately documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb ('retrieves') and resource ('paginated versions of a component'), which clarifies the basic action. However, it does not differentiate from sibling tools like 'retrieve_single_component_version' or 'get_component_usage', leaving ambiguity about when to use this specific tool. The purpose is clear but lacks sibling distinction.
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 mentions 'paginated versions' but does not specify scenarios (e.g., for listing all versions vs. fetching a single one) or reference sibling tools like 'retrieve_single_component_version'. Usage is implied through the term 'paginated' but lacks explicit context or exclusions.
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 are provided, so the description carries the full burden of behavioral disclosure. It states it's a retrieval operation, implying read-only behavior, but doesn't mention any constraints like rate limits, authentication needs, pagination, or what 'multiple releases' entails (e.g., all releases, filtered by criteria). This leaves significant gaps in understanding how the tool behaves.
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, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 the complexity of a retrieval tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is insufficient. It lacks details on behavior, parameter meanings, output format, and differentiation from siblings, making it incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'from a specified Storyblok space,' which hints at the 'space_id' parameter, but doesn't explain 'branch_id' or provide any details on parameter usage, formats, or optionality. This fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('retrieves multiple releases') and resource ('from a specified Storyblok space'), which provides a basic understanding of purpose. However, it doesn't differentiate this tool from sibling tools like 'retrieve_single_release' or other retrieval tools, leaving ambiguity about when to use this specific multi-release retrieval versus alternatives.
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. With sibling tools like 'retrieve_single_release' and 'fetch_stories' available, the description lacks any context about use cases, prerequisites, or comparisons to help an agent choose appropriately.
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 are provided, so the description carries the full burden. It states it retrieves a task, implying a read-only operation, but does not disclose behavioral traits such as authentication needs, error handling, rate limits, or what happens if the task does not exist. The description is minimal and lacks necessary context for safe and effective use.
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 a single sentence that is front-loaded and efficient, with no wasted words. It directly states the tool's purpose without unnecessary elaboration. However, it could be slightly more informative without losing 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?
Given the complexity of a retrieval tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks details on behavior, parameters, return values, and usage context. For a tool interacting with an API, this leaves significant gaps for an AI agent to understand how to invoke it 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?
The input schema has one parameter ('task_id') with 0% description coverage, meaning no schema details are provided. The description does not add any meaning about the parameter, such as what a 'task_id' is, its format, or where to find it. However, with only one parameter, the baseline is higher, but the description fails to compensate for the lack of schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Retrieves') and resource ('a single task'), which is clear but basic. It mentions 'from a specified Storyblok space using the Management API,' adding some context, but does not distinguish it from sibling tools like 'retrieve_multiple_tasks' or 'get_story,' making it vague in comparison. It avoids tautology by not just restating the name.
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. It does not mention sibling tools like 'retrieve_multiple_tasks' for bulk operations or 'get_story' for other resources, nor does it specify prerequisites or contexts for usage. The description is standalone with no implied or explicit usage instructions.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions 'Updates an existing datasource,' implying a mutation, but fails to specify required permissions, whether changes are reversible, rate limits, or response format. This leaves significant gaps in understanding the tool's behavior and safety.
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, clear sentence with no wasted words, making it easy to parse. It is appropriately sized and front-loaded, efficiently conveying the core action without unnecessary elaboration.
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 the complexity of a mutation tool with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It lacks details on parameters, behavioral traits, usage context, and expected outcomes, failing to provide a complete understanding for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning parameters are undocumented in the schema. The description does not add any details about the parameters (datasource_id, dimensions, name, slug), such as their purposes, formats, or constraints. It fails to compensate for the lack of schema documentation, leaving parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Updates an existing datasource in a specified Storyblok space,' which clearly indicates a mutation operation on a specific resource. However, it does not differentiate from sibling tools like 'update_datasource_entry' or 'update_space,' leaving ambiguity about when to use this specific update tool versus others.
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 'create_datasource' for new datasources or other update tools for different resources. It lacks context on prerequisites, exclusions, or comparisons with siblings, offering minimal usage direction.
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 are provided, so the description must fully disclose behavioral traits. It only states the action (update) without details on permissions, side effects, rate limits, or response format. For a mutation tool with 7 parameters, this leaves critical behavioral information unspecified, though it does not contradict any 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, straightforward sentence with no wasted words. It is appropriately sized and front-loaded, making it easy to parse quickly without unnecessary elaboration.
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 the complexity (7 parameters, no schema descriptions, no output schema, and no annotations), the description is incomplete. It does not explain what the tool returns, how updates are applied, or any constraints, leaving too much undefined for effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It mentions no parameters at all, failing to add meaning beyond the schema. With 7 parameters including complex ones like 'branches_to_deploy' and 'release_at,' this is a significant gap that hinders understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Updates an existing release in a specified Storyblok space,' which clearly indicates the verb (update) and resource (release). However, it lacks specificity about what aspects of a release can be updated and does not differentiate from sibling tools like 'update_story' or 'update_space,' making it somewhat vague.
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?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as requiring an existing release ID, or compare it to similar tools like 'create_release' or 'delete_release.' The description provides no context for usage decisions.
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 are provided, so the description carries the full burden. It mentions 'Triggers a backup task' but does not disclose behavioral traits such as whether this is asynchronous, requires specific permissions, has rate limits, or what the expected outcome is (e.g., backup file location). This leaves significant gaps for a mutation 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 a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, clearly stating the tool's purpose without unnecessary details.
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 the complexity of a backup operation (a mutation tool with no annotations, no output schema, and low schema coverage), the description is incomplete. It lacks details on behavior, output, error handling, and usage context, making it inadequate for safe and effective tool 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?
The description does not add any meaning beyond the input schema, which has 0% description coverage for the single parameter 'space_id'. Since schema coverage is low, the description should compensate but does not, resulting in a baseline score of 3 due to the minimal parameter count (1).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Triggers a backup task for a Storyblok space using Management API,' which provides a clear verb ('Triggers') and resource ('backup task for a Storyblok space'). However, it does not differentiate from sibling tools like 'duplicate_space' or specify what 'backup' entails (e.g., data export vs. snapshot), making it somewhat vague.
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. It does not mention prerequisites (e.g., space must exist), timing considerations, or related tools like 'duplicate_space' for similar operations, leaving usage context unclear.
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 are provided, so the description carries full burden. It mentions creation but lacks behavioral details: it doesn't specify required permissions, whether the operation is idempotent, error conditions, or what happens on success (e.g., returns a datasource ID). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every part of the sentence contributes essential information.
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 the complexity (a creation tool with 3 parameters, 0% schema coverage, no annotations, and no output schema), the description is incomplete. It lacks parameter details, behavioral context, usage guidelines, and output information. While concise, it doesn't provide enough context for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning parameters (name, slug, dimensions) are undocumented in the schema. The description adds no parameter information beyond implying a 'specified Storyblok space' (which isn't a parameter listed). It fails to explain what 'dimensions' means or how 'slug' differs from 'name', leaving parameters semantically unclear.
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 ('Creates') and resource ('new datasource') with context ('in a specified Storyblok space'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'create_datasource_entry' or 'create_space', which are related but distinct creation operations.
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. For example, it doesn't mention prerequisites (e.g., needing an existing space), compare to 'create_datasource_entry' (which might add entries to an existing datasource), or specify use cases. The description only states what it does, not when to apply it.
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 are provided, so the description carries the full burden. It states it's a creation operation via the Management API, implying it's a write action, but doesn't disclose behavioral traits such as required permissions, whether it's idempotent, rate limits, or what happens on failure. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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, efficient sentence with zero waste. It's front-loaded with the key action and resource, and appropriately sized for the tool's complexity. Every word earns its place, making it easy to parse quickly.
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 the tool's complexity (7 parameters, nested object, no output schema, and no annotations), the description is incomplete. It lacks details on parameters, behavioral context, and output expectations. For a creation tool in a content management system, more information is needed to guide effective use, such as error handling or success responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 7 parameters have descriptions in the schema. The description adds no information about parameters beyond what the schema provides (only titles like 'Color', 'Component Id'). It doesn't explain what 'preset' object should contain, the format of 'image' or 'icon', or the purpose of 'component_id'. This fails to compensate for the low coverage.
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 ('Creates') and resource ('a new preset in a Storyblok space'), and specifies the API used ('via the Management API'). It distinguishes from siblings like 'update_preset' or 'delete_preset' by indicating creation. However, it doesn't explicitly differentiate from similar creation tools like 'create_component' or 'create_story', which slightly reduces specificity.
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 doesn't mention prerequisites (e.g., needing a space or component), exclusions, or comparisons to siblings like 'retrieve_multiple_presets' for reading. Usage is implied by the verb 'creates', but explicit context is missing.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Supports all documented fields including publishing' which suggests some capabilities, but doesn't address critical behavioral aspects like required permissions, whether creation is reversible, rate limits, or what happens on success/failure. This is inadequate for a mutation tool with zero 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with just two sentences that get straight to the point. The first sentence states the core purpose, and the second adds important capability information. There's no wasted verbiage or unnecessary elaboration.
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 complex mutation tool with 16 parameters, no annotations, no output schema, and 0% schema description coverage, the description is severely incomplete. It doesn't explain what a 'Storyblok story' is in this context, doesn't describe the return value, and provides minimal guidance on the numerous parameters. The agent would struggle to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 16 parameters (3 required), the description provides almost no parameter guidance. It mentions 'all documented fields including publishing' which vaguely references the 'publish' parameter but doesn't explain any of the 15 other parameters or their relationships. The description fails to compensate for the complete lack of schema descriptions.
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 ('Creates') and resource ('a new Storyblok story'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'bulk_create_stories' or 'create_story_schedule', which would require more specific scope information.
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 like 'bulk_create_stories' or 'create_story_schedule'. It mentions 'Supports all documented fields including publishing' which hints at capability but doesn't establish usage context, prerequisites, or exclusions.
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 are provided, so the description carries the full burden of behavioral disclosure. It states it 'Creates a new task', implying a write/mutation operation, but does not disclose any behavioral traits such as required permissions, whether the task is immediately active, error handling, or what the response contains. The mention of 'Management API' hints at administrative access but is not explicit.
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, clear sentence with no wasted words. It is front-loaded with the core action and resource, making it easy to understand at a glance. Every part of the sentence contributes essential information (verb, resource, context).
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 the complexity (6 parameters, 1 required, no schema descriptions, no annotations, no output schema), the description is incomplete. It does not explain what a 'task' entails in Storyblok, what the parameters do, what the tool returns, or any behavioral aspects. For a mutation tool with multiple parameters, this level of detail is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 6 parameters have descriptions in the schema. The tool description does not mention any parameters, their meanings, or how they relate to creating a task (e.g., what 'lambda_code' or 'user_dialog' are for). This leaves all parameters undocumented, failing to compensate for the lack of schema coverage.
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 ('Creates') and the resource ('a new task in a specified Storyblok space'), and mentions the API used ('Management API'). It distinguishes from siblings like 'create_story' or 'create_workflow' by specifying 'task', but does not explicitly differentiate from similar tools like 'create_webhook' or 'create_workflow_stage' that might also create entities in Storyblok.
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 mention prerequisites (e.g., needing a space ID or authentication), nor does it compare to sibling tools like 'create_webhook' or 'update_task'. The context is implied by mentioning 'Storyblok space' and 'Management API', but no explicit usage instructions are 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a creation operation via the Management API, implying a mutation, but doesn't cover permissions, side effects, error handling, or response format. This is inadequate for a mutation tool with 15 parameters.
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, efficient sentence with no wasted words. It is appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.
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 the complexity (15 parameters, mutation operation), lack of annotations, no output schema, and 0% schema coverage, the description is incomplete. It doesn't explain parameters, behavioral traits, or usage context, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning all 15 parameters lack documentation in the schema. The description provides no information about any parameters, not even the required 'name' and 'color', failing to compensate for the schema gap.
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 ('creates') and resource ('new workflow stage in a Storyblok space'), and specifies the API context ('via the Management API'). It distinguishes from siblings like 'create_workflow' or 'update_workflow_stage' by focusing on stage creation, but doesn't explicitly differentiate 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 is provided on when to use this tool versus alternatives like 'create_workflow' or 'update_workflow_stage'. The description lacks context about prerequisites, such as needing an existing workflow or space, or when stage creation is appropriate.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions server-side operations but fails to describe critical behaviors like pagination handling (implied by 'per_page' parameter), authentication requirements, rate limits, or error conditions. This leaves significant gaps for an agent to understand how to invoke it safely.
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 a single, efficient sentence that front-loads the core action and key features. There is no wasted text, though it could benefit from more detail given the complexity of 7 parameters and no annotations.
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 the complexity (7 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It lacks details on parameter usage, behavioral traits, output format, and differentiation from siblings, making it inadequate for an agent to use the tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'server-side filters, sorting, and option to include groups,' which hints at parameters like 'filter_by_name', 'sort_by', and 'in_group', but does not explain their semantics, valid values, or interactions. Other parameters (e.g., 'component_summary', 'include_schema_details') are not addressed at all.
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 ('fetches') and resource ('components'), and specifies server-side operations like filtering, sorting, and including groups. However, it does not explicitly differentiate from sibling tools like 'fetch_component_folders' or 'get_component', which might retrieve similar data but with different scopes or methods.
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 'get_component' (for single component retrieval) or 'fetch_component_folders' (for folder structures). The description mentions features but lacks explicit when-to-use or when-not-to-use instructions.
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 are provided, so the description carries full burden. It states this is a retrieval operation but doesn't disclose behavioral traits like pagination, rate limits, authentication requirements, error conditions, or what 'multiple' implies (e.g., all roles vs. filtered subset). This is inadequate for a tool with parameters.
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, efficient sentence with no wasted words. It's appropriately sized for a simple retrieval tool and front-loads the core purpose.
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 2 parameters with 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain parameter usage, return values, or behavioral constraints, making it insufficient for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so parameters 'by_ids' and 'search' are undocumented in the schema. The description doesn't mention these parameters at all, failing to compensate for the schema gap. This leaves the agent guessing about input semantics.
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 ('retrieves') and resource ('multiple space roles for a given space'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'get_space_role' (singular) or 'retrieve_multiple_*' patterns, which would require a 5.
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 'get_space_role' (singular retrieval) or other retrieval tools. The description merely states what it does without contextual usage instructions.
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 are provided, so the description carries the full burden. It states 'Gets' which implies a read-only operation, but doesn't disclose any behavioral traits such as authentication requirements, error handling (e.g., what happens if the ID is invalid), rate limits, or response format. This leaves significant gaps for safe and effective tool invocation.
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 a single sentence that directly states the tool's function. It is front-loaded and wastes no words, making it easy to parse quickly. This efficiency is appropriate for a simple retrieval tool.
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 the lack of annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain what an 'asset' is, how to handle errors, or what the return value looks like. For a tool in a complex system with many siblings, this minimal description fails to provide sufficient context for reliable use.
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 description mentions 'by ID', which aligns with the single 'id' parameter in the schema. However, with 0% schema description coverage, the schema provides no details about the ID format or constraints. The description adds minimal value by confirming the parameter's purpose but doesn't compensate for the lack of schema documentation, such as specifying if it's a numeric or string ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Gets a specific asset by ID' clearly states the verb ('Gets') and resource ('asset'), making the purpose understandable. However, it lacks specificity about what an 'asset' entails in this context and doesn't differentiate from sibling tools like 'fetch_assets' or 'retrieve_multiple_assets', which could be confusing for an AI agent.
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. With sibling tools like 'fetch_assets' (likely for listing) and 'retrieve_multiple_assets' (likely for batch retrieval), the AI agent receives no explicit or implied context for choosing this single-asset retrieval tool over others.
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?
With no annotations provided, the description carries full burden but only states it retrieves approvals without detailing behavioral traits. It doesn't mention whether this is a read-only operation, if it requires authentication, pagination behavior, rate limits, or what happens with missing parameters.
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 the main purpose, using minimal sentences. However, the second sentence is incomplete as it only covers one parameter, slightly reducing efficiency.
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 no annotations, 0% schema coverage, no output schema, and 3 parameters, the description is incomplete. It lacks details on return values, error handling, and full parameter documentation, making it inadequate for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but only documents one optional parameter ('approver') out of three. It omits 'page' and 'per_page' parameters entirely, leaving significant gaps in 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 action ('Retrieves') and resource ('multiple approvals from a specified Storyblok space'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'retrieve_single_approval' or other retrieval tools, missing explicit sibling distinction.
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 doesn't mention prerequisites, context for filtering, or comparisons to other approval-related tools like 'create_approval' or 'delete_approval'.
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 are provided, so the description carries the full burden. It states the tool retrieves data, implying a read-only operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, pagination, or what 'multiple tags' entails (e.g., all tags, filtered). This is a significant gap for a tool with no 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, making it front-loaded and easy to parse. However, it could be more structured by including key details, but it earns points for brevity.
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 the complexity (a retrieval tool with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It lacks details on behavior, parameters, and output format, making it inadequate for an agent to use the tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter ('search') with 0% description coverage, and the tool description adds no information about parameters. It doesn't explain what 'search' does (e.g., filter tags by name), its format, or how it affects retrieval, failing to compensate for the low schema coverage.
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 ('retrieves') and resource ('multiple tags from a specified Storyblok space'), and mentions the API ('Management API'), which is specific. However, it doesn't differentiate from sibling tools like 'retrieve_multiple_access_tokens' or 'retrieve_multiple_activities', which have similar naming patterns, so it's not fully distinct.
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 doesn't mention any prerequisites, context, or exclusions, such as how it relates to other tag-related tools like 'create_tag' or 'delete_tag', leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool updates roles, permissions, or access paths, implying a mutation operation, but fails to mention critical aspects like required permissions, whether changes are reversible, rate limits, or what the response looks like. This leaves significant gaps in understanding the tool's 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, efficient sentence with no wasted words, clearly stating the tool's purpose. It is appropriately sized and front-loaded, making it easy to understand at a glance without unnecessary elaboration.
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 the complexity of 8 parameters with 0% schema coverage, no annotations, and no output schema, the description is insufficient. It lacks details on parameter meanings, behavioral traits, and expected outcomes, making it incomplete for effective tool use. A mutation tool with this level of undocumented complexity requires more comprehensive guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 8 parameters are documented in the schema. The description only mentions 'roles, permissions, or access paths' in general terms, without explaining specific parameters like 'collaborator_id', 'allowed_paths', or 'field_permissions'. It adds minimal semantic value beyond the tool name, failing to compensate for the lack of schema documentation.
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 ('Updates') and target ('roles, permissions, or access paths for an existing collaborator'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'add_collaborator' or 'delete_collaborator', which would require mentioning it modifies existing collaborators rather than creating or removing 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?
The description provides no guidance on when to use this tool versus alternatives, such as 'add_collaborator' for new collaborators or 'delete_collaborator' for removal. It lacks context on prerequisites, like needing an existing collaborator ID, or exclusions, such as not being for creating collaborators.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Updates an existing Storyblok story by ID,' implying a mutation operation, but lacks details on permissions, side effects (e.g., publishing implications), rate limits, or response format. The mention of 'including publishing' hints at a behavioral trait but is vague and insufficient for comprehensive 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 brief and front-loaded with the core purpose, using only two sentences. However, the second sentence ('Supports all documented fields including publishing.') is somewhat vague and could be more precise, slightly reducing efficiency but overall maintaining good 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?
Given the complexity (22 parameters, 0% schema coverage, no annotations, no output schema), the description is inadequate. It lacks details on parameter semantics, behavioral traits, usage guidelines, and output expectations. For a mutation tool with high parameter count and no structured support, more comprehensive explanation is needed to ensure the agent can invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for 22 undocumented parameters. It only vaguely mentions 'Supports all documented fields including publishing,' which does not explain parameter meanings, usage, or relationships (e.g., 'story_id' as required, 'publish' defaulting to false). This adds minimal value beyond the schema, failing to address the coverage gap.
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 ('Updates') and resource ('an existing Storyblok story by ID'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'bulk_update_stories' or 'create_story', which would be needed for a score of 5.
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 (e.g., 'bulk_update_stories' for multiple updates, 'create_story' for new entries). It mentions 'Supports all documented fields including publishing' but does not specify prerequisites, exclusions, or contextual usage scenarios.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's an update operation but doesn't mention permission requirements, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
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, efficient sentence with no wasted words. It's appropriately sized for a basic tool definition and front-loads the core action, making it easy to parse quickly.
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 the tool's complexity (7 parameters, mutation operation), lack of annotations, 0% schema coverage, and no output schema, the description is inadequate. It doesn't explain parameters, behavioral traits, or return values, leaving the agent poorly equipped to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 7 parameters are documented in the schema. The description adds no information about parameters beyond implying 'webhook_endpoint_id' is needed (from 'existing'), failing to compensate for the complete lack of schema documentation.
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 ('Updates') and resource ('an existing webhook endpoint in a specified Storyblok space'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'add_webhook' or 'delete_webhook', which would require explicit comparison to achieve a score of 5.
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 like 'add_webhook' or 'delete_webhook'. It mentions the resource exists but doesn't specify prerequisites (e.g., needing a webhook_endpoint_id) or contextual constraints, leaving the agent with minimal usage direction.
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?
With no annotations provided, the description carries full burden but only states it's an update operation via the Management API. It doesn't disclose important behavioral aspects like required permissions, whether changes are reversible, rate limits, error conditions, or what happens to workflow stages not mentioned in parameters. For a mutation tool with zero annotation coverage, this is insufficient.
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, efficient sentence with no wasted words. It's appropriately sized for conveying the basic purpose, though it lacks additional helpful context that would be valuable for this type of tool.
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 mutation tool with 3 required parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, what the parameters do, behavioral constraints, or usage context. The agent would struggle to use this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 3 parameters have descriptions in the schema. The tool description provides no information about what the parameters mean, their formats, or how they affect the workflow update. This leaves all parameters completely undocumented.
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 ('Updates') and target ('an existing workflow in a Storyblok space'), and mentions the API context ('via the Management API'). It distinguishes from create_workflow by specifying 'existing workflow', but doesn't explicitly differentiate from other update_* tools like update_workflow_stage.
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 update_workflow_stage or create_workflow. The description implies it's for modifying existing workflows but provides no context about prerequisites, constraints, or typical use cases.
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 are provided, so the description carries full burden. It states this is an update operation via the Management API, implying mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with 15 parameters and no annotation coverage, this is a significant gap.
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 just one sentence that efficiently states the core action and context. There's zero wasted language, and it's properly front-loaded with the essential information.
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 the complexity (15 parameters, mutation operation, no output schema, 0% schema description coverage), the description is severely incomplete. It doesn't explain what a workflow stage is, what fields can be updated, what the update affects, or what the tool returns. For such a complex tool, the single-sentence description is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about any of the 15 parameters. With 0% schema description coverage and no parameter details in the description, the agent has no semantic understanding of what 'after_publish_id', 'allow_admin_change', 'color', etc., actually mean or how they affect the update operation.
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 ('Updates') and resource ('an existing workflow stage in a Storyblok space'), and specifies the API used ('Management API'). However, it doesn't distinguish this tool from sibling update tools like 'update_workflow' or 'update_story', which would require more specific differentiation.
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's no mention of prerequisites (e.g., needing an existing workflow stage), when not to use it, or how it differs from similar tools like 'create_workflow_stage' or other update operations in the sibling list.
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 are provided, so the description carries full burden. It mentions using the 'Management API' which hints at administrative access, but doesn't disclose critical behavioral traits like required permissions, whether this is a mutation (likely yes), rate limits, or what happens on success/failure. For a tool that likely creates resources, this is a significant gap.
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, efficient sentence with zero waste. It's appropriately sized and front-loaded with the core action. Every word 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?
Given 6 parameters with 0% schema coverage, no annotations, no output schema, and complexity of creating a webhook, the description is incomplete. It doesn't explain parameter meanings, behavioral expectations, or return values. The mention of 'Management API' adds some context but insufficient for proper tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all 6 parameters. It adds no information about parameters beyond implying a 'specified Storyblok space' (which isn't even a parameter in the schema). The description doesn't explain what 'actions', 'endpoint', 'name', etc. mean or how they're used.
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 ('Adds a new webhook') and the target resource ('to a specified Storyblok space'), providing specific verb+resource. However, it doesn't differentiate from sibling tools like 'update_webhook' or 'delete_webhook' beyond the basic action difference, which keeps it from a perfect score.
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 like 'update_webhook' or 'delete_webhook', nor does it mention prerequisites such as needing a space ID or Management API access. It only states what the tool does, not when to use it.
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 are provided, so the description carries full burden. It mentions 'using AI' but doesn't disclose key behavioral traits: whether this is a read-only or destructive operation (e.g., does it modify the story?), authentication needs, rate limits, or what happens on failure. For a tool with 6 parameters and no annotations, this is inadequate.
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, efficient sentence with zero waste. It's appropriately sized and front-loaded, stating the core purpose without unnecessary elaboration. Every word 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?
Given the complexity (6 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the tool's behavior, parameter meanings, or expected outcomes. For a translation tool that likely modifies content, more context is needed to guide the agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only implies parameters like 'story' and 'language' but doesn't explain the 6 parameters (e.g., 'code', 'overwrite', 'release_id', 'space_id', 'story_id', 'lang') or their relationships. This leaves critical input semantics undocumented.
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's purpose: 'Translates a story's content into a specified language using AI.' It specifies the verb ('translates'), resource ('story's content'), and method ('using AI'). However, it doesn't distinguish from potential sibling tools like 'bulk_update_stories' or 'update_story' that might also handle translations, so it's not a perfect 5.
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 doesn't mention prerequisites (e.g., needing a story ID), exclusions, or how it differs from other translation-related operations in the sibling list. This leaves the agent guessing about appropriate contexts.
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?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose critical behavioral traits like whether deletions are permanent or reversible, what permissions are required, rate limits, confirmation steps, or error handling for partial failures in bulk operations.
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, efficient sentence with no wasted words. It's appropriately sized for a straightforward tool and front-loads the core action, though this conciseness comes at the cost of completeness.
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 destructive bulk operation with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It doesn't address safety concerns, return values, error conditions, or practical usage details needed for responsible tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions 'multiple stories' but doesn't explain the 'story_ids' parameter format, constraints, or how to obtain valid IDs. It adds minimal semantic value beyond what's implied by the tool name.
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 ('Deletes') and resource ('multiple stories in Storyblok'), making the purpose immediately understandable. However, it doesn't differentiate from the sibling 'delete_story' tool, which appears to handle single story deletion, so it misses explicit sibling distinction.
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 'delete_story' for single deletions or 'bulk_update_stories' for bulk modifications. The description lacks context about prerequisites, permissions, or typical use cases for bulk deletion.
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 are provided, so the description carries full burden. 'Restores' implies a write/mutation operation, but the description doesn't disclose behavioral traits like whether this requires admin permissions, if it's idempotent, what happens on partial failures, or what the return format looks like. It's minimally adequate but lacks crucial details for a mutation 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 extremely concise—a single sentence with no wasted words. It's front-loaded with the core action ('Restores multiple previously deleted assets'), though this brevity comes at the cost of completeness.
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 this is a mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't address permissions, error handling, return values, or how it differs from similar tools, leaving significant gaps for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema only shows 'ids' is a required array of integers. The description adds no parameter semantics—it doesn't explain what 'ids' represent (e.g., asset IDs), format constraints, or valid ranges. With low schema coverage and no compensation in the description, this is insufficient.
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 ('Restores') and resource ('previously deleted assets'), and specifies the scope ('multiple'). However, it doesn't distinguish this tool from potential siblings like 'restore_story' or 'restore_component_version' that might handle different asset types or single restores.
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 doesn't mention prerequisites (e.g., assets must be deleted first), constraints (e.g., rate limits, permissions), or how it differs from single-restore tools like 'restore_story' in the sibling list.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation (implying mutation) and mentions optional publishing, but doesn't cover critical aspects like required permissions, whether changes are reversible, rate limits, error handling for partial failures, or what the response looks like. This leaves significant gaps for a mutation 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 extremely concise (one sentence) with zero wasted words. It's front-loaded with the core purpose and includes the optional publishing feature efficiently.
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 mutation tool with no annotations, 0% schema coverage, no output schema, and one complex parameter (array of objects), the description is inadequate. It doesn't explain what the tool returns, how to structure story objects, error conditions, or behavioral constraints needed for safe use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameter. It mentions 'stories' but provides no details about what constitutes a story object, what fields can be updated, required format, or constraints. The optional publishing aspect isn't linked to any parameter in the schema, creating confusion.
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 ('Updates') and resource ('multiple stories in Storyblok'), making the purpose specific and understandable. However, it doesn't explicitly distinguish this tool from its sibling 'update_story' (which appears to update single stories) or 'bulk_publish_stories' (which publishes without updating), missing full sibling differentiation.
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 like 'update_story' or 'bulk_publish_stories'. It mentions optional publishing but doesn't clarify when that's appropriate or what prerequisites might be needed for bulk operations.
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 are provided, so the description carries the full burden. It states the tool compares versions but doesn't disclose behavioral traits like whether it's read-only or mutating, what the output format is (e.g., diff details), error conditions, or permissions required. This leaves significant gaps for a tool that likely involves data retrieval.
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, efficient sentence with no wasted words. It's front-loaded with the core action and purpose, making it easy to parse quickly.
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 no annotations, 0% schema coverage, no output schema, and two parameters, the description is incomplete. It lacks details on behavior, parameters, output, and usage context, making it inadequate for a tool that likely returns complex comparison data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter information beyond what the schema's property names imply. It doesn't explain what 'story_id' and 'version_v2' represent (e.g., that 'version_v2' might be compared to a current or another version), leaving parameters largely undocumented.
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's purpose with a specific verb ('compares') and resource ('two versions of a story'), and it indicates the outcome ('to identify changes'). It doesn't explicitly differentiate from sibling tools like 'get_story_versions' or 'restore_story', 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing existing story versions, or compare it to siblings like 'get_story_versions' (which might list versions) or 'restore_story' (which might revert to a version).
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 are provided, so the description carries full burden. It states it's a creation tool but doesn't disclose behavioral traits like required permissions, whether the operation is idempotent, what happens on failure, or the format of the response. For a mutation tool with 12 parameters, this is a significant gap.
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, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the core action without unnecessary elaboration.
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 high complexity (12 parameters, nested objects, no output schema, and no annotations), the description is inadequate. It doesn't explain parameter meanings, behavioral expectations, or output format, leaving significant gaps for a creation tool in a system with many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 12 parameters have descriptions in the schema. The description only vaguely mentions 'all supported fields' without explaining what those fields are, their purposes, or relationships. It adds minimal value beyond the schema's property names.
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 'Creates a new component with all supported fields' clearly states the verb ('creates') and resource ('component'), and specifies scope ('with all supported fields'). However, it doesn't distinguish from sibling tools like 'create_component_folder' or 'create_story', which also create different resources in the same system.
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 doesn't mention prerequisites, constraints, or differentiate from other creation tools in the sibling list (e.g., 'create_component_folder' for folders vs. components).
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Creates', implying a write operation, but doesn't cover permissions, side effects, error handling, or response format. This is inadequate for a mutation tool with zero annotation coverage, as critical behavioral traits are missing.
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, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it efficient and easy to parse, though this conciseness comes at the cost of detail.
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 mutation tool with 3 required parameters, 0% schema description coverage, no annotations, and no output schema, the description is incomplete. It lacks details on parameters, behavioral context, and usage guidelines, making it insufficient for an agent to reliably invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter details. The description mentions 'in a specified Storyblok space' but doesn't clarify how this relates to the parameters (datasource_id, name, value) or their purposes. It adds minimal semantic value, failing to compensate for the lack of schema descriptions.
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 ('Creates') and resource ('new datasource entry in a specified Storyblok space'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'create_datasource' or 'update_datasource_entry', which would require more specificity about what a 'datasource entry' entails.
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. It doesn't mention prerequisites (e.g., needing an existing datasource), exclusions, or comparisons with similar tools like 'create_datasource' or 'update_datasource_entry', leaving the agent to infer usage from context alone.
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?
With no annotations provided, the description carries full burden but only states it 'creates' without detailing behavioral aspects like required permissions, whether the operation is idempotent, rate limits, or what happens on failure. It mentions the context parameter but doesn't explain its significance or constraints.
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, well-structured sentence with no wasted words, efficiently conveying the core purpose. It's appropriately sized for a basic tool definition, though it could benefit from additional context.
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 the complexity (19 parameters, 0% schema coverage, no annotations, no output schema), the description is inadequate. It doesn't compensate for the lack of structured data, failing to explain parameter meanings, behavioral traits, or expected outcomes, making it incomplete for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions the 'context' parameter vaguely. With 19 parameters (3 required), it fails to explain key parameters like 'name', 'slug', or optional fields such as 'description' or 'embedded_app_url', leaving most semantics undocumented.
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 ('Creates') and resource ('a new extension'), specifying the context ('organization or partner'). It distinguishes from siblings like 'retrieve_extension' or 'update_extension' by indicating creation, but doesn't explicitly differentiate from other creation tools like 'create_space' or 'create_story'.
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 minimal guidance by mentioning the context parameter, but offers no explicit advice on when to use this tool versus alternatives (e.g., 'update_extension' or other creation tools in the sibling list). There's no mention of prerequisites, dependencies, or typical use cases.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation operation but doesn't mention required permissions, whether it's idempotent, rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is inadequate.
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, efficient sentence with zero waste. It's appropriately sized and front-loaded, making it easy to parse quickly.
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 5 parameters (1 required), 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain the release creation process, parameter meanings, or expected outcomes, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 5 parameters are documented in the schema. The description adds no parameter information beyond the tool name, failing to compensate for the schema gap. It doesn't explain what 'name', 'branches_to_deploy', etc., mean or how to use them.
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 ('creates') and resource ('new release in a specified Storyblok space'), providing specific verb+resource. However, it doesn't differentiate from sibling tools like 'create_release_approval' or 'create_story_schedule', which would require a 5.
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 like 'create_release_approval' or 'update_release', nor does it mention prerequisites or context. It merely states what the tool does without usage instructions.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation via the Management API, implying it's a write/mutation tool, but doesn't mention permission requirements, rate limits, whether it's idempotent, what happens on failure, or what the response contains. This leaves significant behavioral gaps for a mutation 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 extremely concise at just one sentence with zero wasted words. It's front-loaded with the core purpose and includes the API context. Every word earns its place, making it efficient despite its brevity.
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 mutation tool with 4 parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what a Storyblok space is, what parameters control, what the creation entails, or what to expect in return. The agent lacks sufficient context to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It provides no information about the 4 parameters (name, domain, environments, story_published_hook) beyond what's in the schema titles. The description doesn't explain what these parameters mean, their formats, or how they affect space creation.
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 ('Creates') and resource ('a new Storyblok space'), providing specific verb+resource pairing. However, it doesn't distinguish this tool from sibling tools like 'duplicate_space' or 'update_space' that also involve space creation/modification, which prevents a perfect score.
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 doesn't mention prerequisites, when not to use it, or differentiate from similar tools like 'duplicate_space' or 'update_space' in the sibling list. The agent must infer usage from context alone.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'specific permissions' but doesn't explain what permissions are available, whether this is a destructive operation, what authentication is required, or what the output looks like. This is inadequate for a creation tool with 11 parameters.
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, well-structured sentence with no wasted words. It's appropriately sized and front-loaded with the core action, making it efficient and easy to parse.
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 the complexity (11 parameters, no annotations, no output schema), the description is incomplete. It lacks details on permissions, output format, error conditions, and how it differs from sibling tools. This makes it insufficient for an AI agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It only vaguely mentions 'specific permissions', which hints at some parameters but doesn't clarify the 11 input fields (e.g., 'role_name', 'allowed_languages', 'asset_folder_ids'). This leaves most parameters undocumented.
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 ('Creates') and resource ('a new custom space role with specific permissions'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'create_space' or 'create_workflow', which also create resources, so it doesn't reach the highest score.
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 like 'update_space_role' or 'fetch_space_roles', nor does it mention prerequisites or exclusions. It only states what it does, not when it's appropriate.
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 are provided, so the description carries the full burden of behavioral disclosure. It states this is a creation operation, implying mutation, but doesn't cover critical aspects like required permissions, whether the tag is immediately available, error handling, or rate limits. This leaves significant gaps for a tool that modifies data.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly, though it could benefit from more detail given the tool's complexity.
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 the lack of annotations, 0% schema description coverage, and no output schema, the description is insufficient for a mutation tool. It doesn't explain parameters, behavioral traits, or return values, leaving the agent with minimal guidance beyond the basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no descriptions for parameters. The description adds no information about the parameters, such as what 'name' and 'story_id' represent, their formats, or constraints. For a tool with 2 parameters, this lack of detail is inadequate.
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 ('Creates') and resource ('a new tag in a Storyblok space via the Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'create_internal_tag' or 'update_tag', which would require more detail about what makes this tool unique.
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 doesn't mention prerequisites, such as needing a specific space or permissions, or compare it to similar tools like 'create_internal_tag' or 'update_tag', leaving the agent without context for selection.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation operation but doesn't mention required permissions, whether it's idempotent, what happens on failure, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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, efficient sentence with no wasted words. It's appropriately sized for a basic tool definition and gets straight to the point without unnecessary elaboration.
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 creation tool with 2 required parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what parameters mean, what the tool returns, or important behavioral aspects like permissions or error handling that would be crucial for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The tool description doesn't mention any parameters at all, failing to compensate for the complete lack of schema documentation. The two required parameters ('name' and 'content_types') remain entirely unexplained in both schema and description.
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 ('Creates') and resource ('a new workflow in a Storyblok space'), specifying it uses the Management API. However, it doesn't distinguish this tool from sibling tools like 'create_workflow_stage' or 'duplicate_workflow', which are related but different operations.
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 doesn't mention prerequisites, when this operation is appropriate, or what distinguishes it from similar tools like 'update_workflow' or 'duplicate_workflow' in the sibling list.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'creates' something, implying a write/mutation operation, but does not disclose any behavioral traits such as required permissions, whether the change is reversible, rate limits, or what the response looks like. This is a significant gap for a mutation 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 a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, clearly stating the core action and context without unnecessary elaboration.
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 the complexity of a mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks essential details such as parameter explanations, behavioral context, and usage guidelines, making it inadequate for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate by explaining the parameters. However, it adds no meaning beyond what the schema provides—it does not clarify what 'story_id' or 'workflow_stage_id' represent, their formats, or how they relate to the creation process. This leaves parameters largely undocumented.
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 ('creates a new workflow stage change') and the resource ('for a story in a Storyblok space via the Management API'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'update_workflow_stage' or 'retrieve_multiple_workflow_stage_changes', which would be needed for a score of 5.
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 workflow-related tools in the sibling list (e.g., 'create_workflow', 'create_workflow_stage', 'update_workflow_stage'). There is no mention of prerequisites, context, or exclusions, leaving usage unclear.
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 are provided, so the description carries full burden. It states this is a deletion operation, implying it's destructive, but doesn't disclose critical behavioral traits: whether deletion is permanent or reversible, if it requires specific permissions, what happens to associated data, or error conditions. For a destructive tool with zero annotation coverage, this is a significant gap.
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 with no wasted words. It's front-loaded with the core action and resource. While it lacks detail, what's present is structured efficiently without redundancy.
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 destructive deletion tool with 1 parameter, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral implications, parameter meaning, or expected outcomes. The agent would struggle to use this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the single parameter (datasource_id) has no documentation in the schema. The description adds no information about this parameter—it doesn't explain what a datasource_id is, how to obtain it, or format requirements. The description fails to compensate for the schema's lack of documentation.
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 ('Deletes') and resource ('a datasource from a specified Storyblok space'), making the purpose understandable. However, it doesn't distinguish this tool from other deletion tools in the sibling list (e.g., delete_asset, delete_story, delete_datasource_entry), which would require mentioning what makes datasource deletion unique.
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 doesn't mention prerequisites (e.g., needing a datasource_id), consequences of deletion, or when to choose other tools like delete_datasource_entry. This leaves the agent without contextual usage information.
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 are provided, so the description carries full burden. It states this is a deletion operation, implying it's destructive, but doesn't specify if it's irreversible, requires permissions, or has side effects (e.g., impacting associated data). The description lacks details on error handling, confirmation steps, or response format, leaving behavioral gaps for a mutation 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 a single, well-structured sentence with no wasted words. It front-loads the core action ('Deletes an existing extension') and efficiently adds context details. Every part earns its place, making it highly concise.
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 deletion tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It lacks details on permissions, irreversibility, error cases, and parameter specifics (especially 'extension_id'). Given the complexity of a destructive operation, more context is needed to ensure safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'context (organization or partner)', which clarifies one parameter's purpose, but doesn't explain 'extension_id' (e.g., what it refers to, format, or how to obtain it). With 2 parameters and low coverage, the description adds minimal value 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 verb ('Deletes') and resource ('an existing extension'), making the purpose unambiguous. It specifies the context ('organization or partner'), which adds clarity. However, it doesn't explicitly differentiate from sibling tools like 'delete_webhook' or 'delete_field_plugin', which also delete resources but different 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?
The description mentions the context parameter ('organization or partner'), which provides some usage context, but offers no explicit guidance on when to use this tool versus alternatives like 'delete_extension' vs. 'update_extension' or other deletion tools. There are no prerequisites, exclusions, or comparisons to sibling tools listed.
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 are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Deletes') but doesn't cover critical aspects like whether this is destructive (implied but not explicit), permission requirements, error handling (e.g., if the tag doesn't exist), or what happens upon success (e.g., confirmation message). This leaves significant gaps for a mutation 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 a single, direct sentence with no wasted words, making it highly concise and front-loaded. It efficiently communicates the core action without unnecessary elaboration.
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 the tool's complexity (a destructive mutation with no annotations, 0% schema coverage, and no output schema), the description is insufficient. It lacks details on parameters, behavioral traits, usage context, and expected outcomes, making it inadequate for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, with one parameter 'id' undocumented in the schema. The description adds no information about this parameter, such as what 'id' refers to (e.g., tag ID from Storyblok), where to obtain it, or format requirements. This fails to compensate for the lack of schema documentation.
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 ('Deletes') and the resource ('a tag from Storyblok'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_internal_tag' or 'update_tag', which would require specifying this is for standard tags versus internal tags or other tag operations.
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. For example, it doesn't mention prerequisites (e.g., needing the tag ID from 'retrieve_multiple_tags'), exclusions (e.g., cannot delete tags in use), or related tools like 'create_tag' or 'update_tag' for other tag operations.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a deletion operation using the Management API, implying it's destructive, but doesn't specify if deletion is permanent, requires specific permissions, has rate limits, or what happens to associated data. For a mutation tool with zero annotation coverage, this leaves significant gaps.
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, efficient sentence with zero wasted words. It's appropriately sized and front-loaded with the core action, making it easy to parse quickly.
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 this is a destructive mutation tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It doesn't address critical aspects like error conditions, confirmation requirements, or what the tool returns. The context signals indicate high complexity that isn't adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'task_id' implicitly through context but doesn't explain what a task ID is, where to find it, or its format. The single parameter remains largely unexplained beyond what's inferred from the tool name.
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 ('Deletes') and resource ('an existing task in a specified Storyblok space'), providing specific verb+resource. However, it doesn't distinguish this from other deletion tools like delete_story or delete_asset, which would require sibling differentiation for a score of 5.
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's no mention of prerequisites (e.g., task must exist), when-not-to-use scenarios, or comparison to similar tools like delete_multiple_tasks (which doesn't exist in siblings but could be relevant).
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?
With no annotations provided, the description carries full burden but only states the action without behavioral details. It doesn't disclose that this is a destructive operation, potential side effects (e.g., stopping notifications), permission requirements, or error conditions, which are critical for a deletion 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 a single, well-structured sentence with no wasted words. It front-loads the key action and resource, making it efficient and easy to parse, which is ideal for 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?
For a destructive tool with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It lacks critical context like behavioral risks, parameter guidance, and outcome details, leaving the agent under-informed about this high-stakes operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter information beyond implying a 'webhook_endpoint_id' is needed. It doesn't explain what this ID is, how to obtain it (e.g., from 'retrieve_single_webhook'), or format constraints, failing to compensate for the schema gap.
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 ('Deletes') and resource ('an existing webhook endpoint in a specified Storyblok space'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'delete_webhook' vs 'add_webhook' or 'update_webhook' beyond the verb, which prevents a perfect score.
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 doesn't mention prerequisites (e.g., needing an existing webhook), exclusions, or related tools like 'retrieve_single_webhook' for verification, leaving the agent without contextual usage cues.
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 are provided, so the description carries full burden. It states the tool deletes a workflow stage, implying a destructive mutation, but doesn't disclose critical behavioral traits like whether deletion is permanent, requires specific permissions, affects related data, or has side effects. This leaves significant gaps for a mutation tool with zero 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 a single, efficient sentence with no wasted words, front-loading the core action. It's appropriately sized for a simple tool, though brevity contributes to gaps in other dimensions.
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 the tool's complexity as a destructive mutation with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks details on parameters, behavioral implications, error handling, and return values, making it insufficient for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, with one parameter ('workflow_id') documented only by title and type in the schema. The description adds no meaning beyond the schema, failing to explain what 'workflow_id' represents, how to obtain it, or its format. For a single parameter with no schema descriptions, this is inadequate.
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 ('Deletes') and resource ('a workflow stage in a Storyblok space'), and mentions the API context ('via the Management API'), which is specific. However, it doesn't differentiate from sibling tools like 'delete_workflow' or 'delete_workflow_stage_change', which target similar resources, leaving some ambiguity about scope.
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 'delete_workflow' for deleting entire workflows or 'update_workflow_stage' for modifications. The description lacks context about prerequisites, permissions, or typical scenarios for deletion, offering minimal usage direction.
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?
With no annotations provided, the description carries full burden but only states what the tool does without behavioral details. It doesn't disclose whether this is a destructive operation, what permissions are required, how long it takes, or what happens to the original space. For a mutation tool with zero annotation coverage, this is a significant gap.
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, efficient sentence with no wasted words. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.
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 complex mutation tool with 7 parameters, 0% schema coverage, no output schema, and no annotations, the description is inadequate. It doesn't explain what duplication entails (content, settings, both?), success indicators, error conditions, or return values. The description leaves too many open questions for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'original_space_id' or 'new_space_name' mean, nor the purpose of optional parameters like 'domain' or 'environments'. The description fails to provide any semantic context beyond the schema's bare titles.
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 ('duplicates') and resource ('an existing Storyblok space'), with specific reference to the Management API. It distinguishes from siblings like 'create_space' by focusing on duplication rather than creation from scratch, though it doesn't explicitly contrast 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 is provided on when to use this tool versus alternatives like 'create_space' or 'backup_space', nor any prerequisites or context for duplication. The description lacks usage context, leaving the agent to infer based on tool name alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool duplicates a workflow but doesn't explain what duplication entails (e.g., whether it copies all settings, stages, or content types), what permissions are required, whether it's a safe operation, or what the output looks like. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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, well-structured sentence with zero waste. It efficiently communicates the core purpose and context without unnecessary words. Every part of the sentence earns its place by specifying the action, resource, and API context.
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 the tool has 3 required parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain parameter meanings, behavioral details, or expected outcomes. For a mutation tool with significant complexity, the description should provide more context about how duplication works and what results to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions duplicating a workflow but doesn't explain any of the three required parameters (workflow_id, name, content_types). It doesn't clarify what 'content_types' represents in this context or how the duplication process uses these inputs, leaving parameters semantically undefined.
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 ('duplicates') and resource ('an existing workflow in a Storyblok space'), and specifies the API context ('via the Management API'). It distinguishes from siblings like 'create_workflow' by focusing on duplication rather than creation from scratch. However, it doesn't explicitly differentiate from 'duplicate_space' or other duplication tools in the sibling list.
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 'create_workflow' or other duplication tools. The description mentions the Management API context but doesn't specify prerequisites, permissions needed, or scenarios where duplication is preferred over creation. This leaves the agent without clear usage context.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'retrieve' which implies a read operation, but doesn't mention pagination behavior (despite 'page' and 'per_page' parameters), rate limits, authentication requirements, or what format/assets are returned. The description adds minimal behavioral context beyond the basic 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 extremely concise at just one sentence with no wasted words. It's front-loaded with the core purpose and efficiently communicates the basic operation. Every word earns its place in this minimal description.
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 10 parameters, no annotations, no output schema, and 0% schema description coverage, the description is severely inadequate. It provides only the basic operation without explaining parameter usage, behavioral constraints, or return format. The description doesn't compensate for the lack of structured documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 10 parameters and 0% schema description coverage, the description provides no information about any parameters. It doesn't explain what 'by_alt', 'by_copyright', 'folder_id', 'is_private', 'sort_by' options, or other parameters mean or how they affect the retrieval. The description fails to compensate for the complete lack of parameter documentation in 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 verb 'retrieve' and resource 'multiple assets' with the source 'Storyblok Management API'. It distinguishes from sibling tools like 'get_asset' (singular) and 'bulk_move_assets' (mutation), but doesn't explicitly differentiate from other retrieval tools like 'fetch_stories' or 'retrieve_asset_folders'.
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 doesn't mention when to choose 'fetch_assets' over 'get_asset' (singular retrieval) or 'retrieve_asset_folders' (folder listing), nor does it specify prerequisites or appropriate contexts for asset retrieval.
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 are provided, so the description carries the full burden. It mentions the scope (draft & published stories) but doesn't disclose critical behavioral traits such as whether this is a read-only operation, how results are returned (e.g., pagination, format), performance implications, or error handling. The description is too sparse for a tool with no 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 a single, efficient sentence with no wasted words. It's front-loaded with the core purpose and includes a useful detail (draft & published). Every part earns its place, making it highly concise and well-structured.
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 the complexity (a search tool with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It lacks details on parameters, return values, behavioral constraints, and differentiation from siblings. For a tool that likely returns multiple stories, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, with one parameter 'component_name' undocumented. The description doesn't add any parameter semantics—it doesn't explain what 'component_name' refers to (e.g., a specific identifier, name pattern), its format, or examples. This fails to compensate for the low schema coverage.
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 ('Finds stories') and resource ('where a component is used in content'), specifying both draft and published states. It distinguishes from generic story-fetching tools by focusing on component usage, but doesn't explicitly differentiate from similar tools like 'fetch_stories' or 'get_story' that might also retrieve stories.
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 minimal guidance, implying usage when searching for component references in stories. However, it doesn't specify when to use this versus alternatives like 'fetch_stories' (which might have filtering capabilities) or 'get_story' (for single stories), nor does it mention prerequisites or exclusions.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the API ('Storyblok Management API') but doesn't describe key traits like whether this is a read-only operation, potential error conditions (e.g., invalid ID), rate limits, or what the output looks like. This leaves significant gaps for an agent to understand how to handle the tool effectively.
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, well-structured sentence that efficiently conveys the core action and resource without unnecessary words. It's front-loaded with the key information ('Retrieve a single space role by ID') and adds only essential context ('via the Storyblok Management API'), making it highly concise and easy to parse.
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 the complexity of a retrieval tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks details on behavior, parameter meaning, output format, and usage context, making it insufficient for an agent to confidently invoke the tool without additional assumptions or errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 0% description coverage, and the tool description doesn't add any semantic details about the 'space_role_id' parameter. It doesn't explain what a space role ID is, where to find it, or its expected format (e.g., integer range, uniqueness), leaving the parameter meaning unclear beyond the schema's basic type.
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 ('Retrieve') and resource ('a single space role by ID'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'fetch_space_roles' or 'retrieve_single_activity', which might have similar retrieval patterns but for different resources.
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. For example, it doesn't mention if this is for looking up a specific space role ID versus listing multiple roles with 'fetch_space_roles', or clarify prerequisites like authentication or permissions needed to access space roles.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic retrieval action without mentioning permissions needed, rate limits, error handling, or what data is returned. For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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, clear sentence with no wasted words. It's front-loaded with the core action and efficiently communicates the essential function without unnecessary elaboration.
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 no annotations, 0% schema coverage, and no output schema, the description is incomplete. It doesn't explain what a 'story' entails in this context, what data is returned, or any behavioral aspects like authentication or errors. For a tool with one parameter and no structured documentation, it should provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the parameter 'story_id' is undocumented in the schema. The description mentions 'by its ID' which adds minimal context about the parameter's purpose, but doesn't specify format constraints (e.g., integer type, valid ranges) or where to obtain the ID. It partially compensates but not enough for the coverage gap.
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 ('retrieves') and resource ('a specific story by its ID'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'fetch_stories' (which likely retrieves multiple stories) or 'get_story_versions' (which retrieves version history), so it doesn't fully distinguish from alternatives.
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 like 'fetch_stories' or 'get_story_versions'. It states what it does but offers no context about appropriate use cases, prerequisites, or exclusions.
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 are provided, so the description carries full burden. It states 'Retrieves' which implies a read-only operation, but doesn't disclose pagination behavior (implied by page/per_page parameters), authentication needs, rate limits, error conditions, or what format the versions are returned in. The description adds minimal behavioral context beyond the basic action.
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 just one sentence that directly states the tool's purpose. There's no wasted language or unnecessary elaboration, making it front-loaded and 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 6 parameters (0% schema coverage), no annotations, and no output schema, the description is insufficient. It doesn't explain what 'versions' or 'revisions' mean in this context, doesn't describe the return format, and provides no guidance on parameter usage. The minimal description leaves too many open questions for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but doesn't mention any parameters. With 6 parameters (1 required), the description provides no information about by_story_id requirement, pagination controls (page/per_page), filtering options (by_release_id, version_id), or content display (show_content). This leaves significant gaps in understanding parameter usage.
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 ('Retrieves') and resource ('versions (revisions) of stories'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'retrieve_story_versions' (if it existed) or explain how it differs from 'get_story' or 'fetch_stories' in terms of version-specific retrieval.
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. With many sibling tools for story operations (get_story, fetch_stories, compare_story_versions, etc.), the description doesn't indicate whether this is for historical versions, draft revisions, or how it relates to other story retrieval tools.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data, implying a read-only operation, but doesn't specify if it requires authentication, has rate limits, or what happens with invalid inputs. This leaves significant gaps in understanding the tool's behavior and constraints.
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 a single sentence that directly states the tool's action. It's front-loaded and wastes no words, making it easy to parse quickly, though this brevity comes at the cost of detail in other dimensions.
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 the complexity of retrieving dependencies with two parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover parameter details, behavioral traits, or return values, making it inadequate for an agent to use the tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'one or more stories', which loosely relates to the 'story_ids' parameter, but doesn't explain the 'release_id' parameter or its purpose. With 0% schema description coverage and two parameters, the description fails to add meaningful semantics beyond what's implied, leaving key inputs undocumented.
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's purpose with a specific verb ('Retrieves') and resource ('unpublished dependencies for one or more stories'), making it immediately understandable. However, it doesn't differentiate from sibling tools like 'fetch_stories' or 'get_story', which might also retrieve story-related data, leaving room for ambiguity in tool selection.
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 doesn't mention prerequisites, such as needing specific permissions or story states, or compare it to similar tools like 'fetch_stories' or 'get_story_versions', leaving the agent to infer usage 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Publishes' implies a write operation, it doesn't specify whether this is destructive, requires specific permissions, has side effects (e.g., triggering webhooks), or what happens on failure. For a mutation tool with zero annotation coverage, this is a significant gap.
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, efficient sentence with no wasted words. It is appropriately sized and front-loaded, clearly stating the core action without unnecessary elaboration.
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 the complexity of a publish operation (a mutation with potential side effects), no annotations, no output schema, and incomplete parameter documentation, the description is inadequate. It should explain behavioral traits, parameter purposes, and expected outcomes to be complete for this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the three parameters (story_id, lang, release_id) are documented in the schema. The description only mentions 'by its ID', which partially explains the required 'story_id' parameter but ignores the optional 'lang' and 'release_id' parameters. It adds minimal value 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 verb ('Publishes') and resource ('a Storyblok story by its ID'), making the purpose specific and understandable. However, it doesn't distinguish this tool from sibling tools like 'bulk_publish_stories' or 'unpublish_story', which would require explicit differentiation to achieve a perfect score.
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 like 'bulk_publish_stories' or 'unpublish_story'. It also lacks information about prerequisites (e.g., whether the story must be in a draft state) or contextual constraints, leaving the agent without usage direction.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Restores' implies a mutation operation, it doesn't specify whether this is destructive (overwrites current version), requires specific permissions, has side effects, or what happens on success/failure. The description lacks crucial behavioral context for a tool that modifies system state.
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 at just one sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place in conveying the essential purpose.
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 mutation tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what 'restore' entails operationally, what parameters mean, what the tool returns, or how it differs from similar tools. The agent would struggle to use this correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions 'component' and 'previous version' which loosely map to the two parameters, but doesn't explain what component_id and version_id represent, their format, or how to obtain valid values. This leaves significant gaps in 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 verb ('Restores') and resource ('a component to a previous version'), making the purpose understandable. However, it doesn't distinguish this tool from sibling tools like 'restore_story' or 'bulk_restore_assets', which perform similar restoration operations on different resource 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing to retrieve component versions first), nor does it differentiate from similar restoration tools in the sibling list, leaving the agent to guess based on naming alone.
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 are provided, so the description carries full burden. It states 'retrieve' implying a read-only operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or what happens if the extension/space doesn't exist. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
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, efficient sentence with no wasted words. It's appropriately sized for a simple retrieval tool and front-loads the core action ('retrieve settings'). Every word earns its place by conveying essential information.
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 no annotations, 0% schema coverage, and no output schema, the description is incomplete. It doesn't explain what settings are returned, the response format, error handling, or usage context. For a tool with two required parameters and no structured documentation, this minimal description leaves too many questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'extension in a space' which hints at the two parameters (extension_id, space_id), but doesn't explain their semantics, formats, or constraints beyond what's obvious from the names. It fails to compensate for the lack of schema documentation.
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 'retrieve' and the resource 'settings for a specific extension in a space', making the purpose unambiguous. It distinguishes from siblings like 'retrieve_extension' (which gets extension details) and 'retrieve_all_extension_settings' (which gets all settings). However, it doesn't specify what types of settings are retrieved, leaving some ambiguity.
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 doesn't mention prerequisites, when not to use it, or compare it to siblings like 'retrieve_all_extension_settings' for bulk retrieval or 'retrieve_extension' for extension metadata. The agent must infer usage from the tool name alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions pagination ('paginated list'), which is useful, but fails to cover critical aspects like whether this is a read-only operation, authentication requirements, rate limits, error handling, or the format of returned data. For a tool with zero annotation coverage, this leaves significant gaps.
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, well-structured sentence that efficiently conveys the core functionality without unnecessary words. It is front-loaded with the main action and resource, making it easy to parse quickly.
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 the tool's complexity (2 parameters, no output schema, no annotations), the description is incomplete. It lacks details on parameter usage, behavioral traits like safety or permissions, and output format. While concise, it doesn't provide enough context for an agent to use the tool effectively without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning parameters 'page' and 'per_page' are undocumented in the schema. The description adds no information about these parameters—it doesn't explain their purpose, default values, valid ranges, or how they affect pagination. This fails to compensate for the schema's lack of descriptions.
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 ('retrieves'), resource ('collaborators (users)'), and context ('in a specified Storyblok space'), making the purpose understandable. It doesn't explicitly differentiate from sibling tools like 'fetch_space_roles' or 'retrieve_single_activity', but the specificity is adequate for basic understanding.
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 like 'fetch_space_roles' or 'retrieve_multiple_activities', nor does it mention prerequisites or context. It simply states what it does without indicating appropriate scenarios or exclusions.
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 are provided, so the description carries full burden for behavioral disclosure. The description only states what the tool does at a high level without mentioning permissions required, pagination behavior, rate limits, error conditions, or what constitutes a 'datasource' in Storyblok context. For a retrieval tool with zero annotation coverage, this leaves significant behavioral gaps.
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 that gets straight to the point without any unnecessary words. It's front-loaded with the core functionality and wastes no space on redundant information. This is an example of efficient communication, though it achieves this at the expense of completeness.
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 the tool has 2 parameters with 0% schema coverage, no annotations, and no output schema, the description is inadequate. It provides only basic purpose information without addressing parameter usage, behavioral characteristics, or output format. For a tool that likely returns structured data about datasources, more context is needed about what information is returned and how to interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning neither parameter ('by_ids' or 'search') has any documentation in the schema. The description provides no information about these parameters - it doesn't explain what format 'by_ids' should take, what the 'search' parameter filters on, or how they interact. With 2 undocumented parameters, the description fails to compensate for the schema's deficiencies.
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 ('retrieves') and resource ('multiple datasources from a specified Storyblok space'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'retrieve_single_datasource' or 'retrieve_multiple_datasource_entries', which would require more specificity about scope or relationship to other datasource operations.
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 about when to use this tool versus alternatives. With sibling tools like 'retrieve_single_datasource' and 'retrieve_multiple_datasource_entries' available, the description offers no context about selection criteria, prerequisites, or typical use cases for retrieving multiple datasources versus other retrieval operations.
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 are provided, so the description carries full burden. It mentions the 'Management API' but doesn't disclose behavioral traits like pagination (implied by 'page' and 'per_page' parameters), authentication needs, rate limits, error handling, or what 'tasks' represent in Storyblok. The description is minimal and lacks operational 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 a single, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to scan. Every part earns its place by specifying the API context.
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 the complexity (3 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain parameter usage, return values, or behavioral aspects like pagination or errors. For a retrieval tool with multiple parameters, this leaves significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so parameters are undocumented in the schema. The description adds no meaning beyond the tool name—it doesn't explain what 'space_id', 'page', or 'per_page' are, their formats, or how they affect retrieval. This fails to compensate for the schema gap.
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 ('retrieves') and resource ('multiple tasks from a specified Storyblok space'), and mentions the API ('Management API'). It distinguishes from siblings like 'retrieve_single_task' by specifying 'multiple', but doesn't explicitly differentiate from other list/retrieval tools like 'retrieve_multiple_stories' or 'fetch_stories'.
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. With many sibling tools for retrieving various resources (e.g., 'retrieve_multiple_stories', 'fetch_stories', 'retrieve_single_task'), the description lacks context on use cases, prerequisites, or comparisons.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a retrieval operation using the Management API, implying read-only behavior, but doesn't specify authentication requirements, rate limits, error conditions, or what format the webhooks are returned in. For a tool with no annotation coverage, this leaves significant behavioral gaps.
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, efficient sentence with zero wasted words. It's appropriately sized for a retrieval tool and front-loads the essential information. Every word earns its place in conveying the core functionality.
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 retrieval tool with 2 parameters, 0% schema description coverage, no annotations, and no output schema, the description is incomplete. It covers the basic purpose but lacks parameter explanations, behavioral context, usage guidance, and output format information. The agent would struggle to use this tool effectively without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning neither parameter has descriptions in the schema. The description provides no information about the 'page' and 'per_page' parameters, their purpose, valid ranges, or how they affect pagination. The description doesn't compensate for the complete lack of parameter documentation in 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 ('Retrieves') and resource ('multiple webhook endpoints from a specified Storyblok space'), providing specific verb+resource information. It distinguishes from 'retrieve_single_webhook' by indicating 'multiple' endpoints. However, it doesn't explicitly differentiate from other list/retrieve tools like 'fetch_stories' or 'retrieve_multiple_access_tokens' beyond 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. It doesn't mention when this tool is appropriate, what prerequisites exist (e.g., needing a specific space), or when to choose other webhook-related tools like 'retrieve_single_webhook', 'add_webhook', or 'delete_webhook'. The only contextual clue is the resource type.
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 are provided, so the description carries the full burden. It states it 'retrieves' schema details, implying a read-only operation, but doesn't disclose behavioral traits like whether it requires authentication, has rate limits, returns errors for invalid IDs, or what format the schema details are in. This is a significant gap for a tool with no 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 a single, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it efficient and easy to parse.
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 the complexity (a retrieval tool with 2 required parameters), no annotations, no output schema, and 0% schema coverage, the description is incomplete. It doesn't compensate for the lack of structured data, leaving gaps in parameter meaning, behavioral context, and output details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no descriptions for the two parameters. The description mentions 'specific component version' but doesn't explain what 'component_id' and 'version_id' represent, their formats, or where to obtain them. It adds minimal value beyond the schema's basic structure.
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 ('retrieves') and resource ('schema details of a specific component version'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'retrieve_component_versions' (plural) or 'get_component', which might retrieve different aspects of components.
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 like 'retrieve_component_versions' or 'get_component'. It lacks context about prerequisites, such as needing a specific component and version ID, or when this retrieval is appropriate compared to other retrieval methods.
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 are provided, so the description carries full burden. It mentions the Management API but doesn't disclose behavioral traits like whether it's read-only, requires authentication, has rate limits, or what the return format looks like. For a retrieval tool with zero annotation coverage, this leaves significant gaps in understanding its 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 a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration. Every part of the sentence contributes to understanding the tool.
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 the complexity of a retrieval tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks details on parameters, return values, behavioral constraints, and usage context. For a tool interacting with an API, more information is needed to ensure correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, with one parameter ('preset_id') undocumented in the schema. The description does not add any meaning about the parameter, such as what a preset ID is, where to find it, or its format (e.g., integer). It fails to compensate for the low schema coverage, leaving the parameter's purpose unclear.
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 ('retrieves') and resource ('a single preset from a Storyblok space'), and specifies the API ('Management API'). It distinguishes from siblings like 'retrieve_multiple_presets' by indicating 'single', but doesn't explicitly contrast them. The purpose 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 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 'retrieve_multiple_presets' or 'get_story'. The description lacks context about prerequisites, such as needing a preset ID, or when this retrieval is appropriate compared to bulk operations. Usage is implied but not stated.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the 'Management API' but doesn't specify authentication requirements, rate limits, error conditions, or what the return format looks like (especially since there's no output schema). For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to scan and understand quickly.
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 the complexity (a read operation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It lacks details on authentication, response format, error handling, and how it differs from sibling tools. For a tool that retrieves data, this minimal description doesn't provide enough context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameter. It doesn't explain what 'webhook_endpoint_id' represents, how to obtain it, or its format beyond the schema's 'integer' type. The description adds no parameter-specific information, failing to address the coverage gap.
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 ('retrieves') and resource ('a single webhook from a specified Storyblok space'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'retrieve_multiple_webhooks' or 'get_story', which are similar retrieval operations on different resources.
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 doesn't mention prerequisites (e.g., needing a specific space or permissions), compare it to 'retrieve_multiple_webhooks', or indicate scenarios where retrieving a single webhook is preferred over other operations.
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 are provided, so the description carries the full burden of behavioral disclosure. It states this is a retrieval operation via the Management API, implying it's likely read-only, but doesn't confirm safety, permissions, rate limits, or response format. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 the lack of annotations, no output schema, and low schema description coverage, the description is incomplete. It doesn't address behavioral traits, parameter details, or return values, leaving the agent with insufficient context for reliable tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, with one parameter ('workflow_id') undocumented in the schema. The description mentions 'by its ID' but doesn't add details like ID format, source, or constraints. It provides minimal value beyond the schema, failing to compensate for the coverage gap.
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 ('Retrieves') and resource ('a single workflow by its ID in a Storyblok space via the Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_multiple_workflows' or 'get_story', which would be needed for a perfect score.
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 doesn't mention sibling tools like 'retrieve_multiple_workflows' for bulk retrieval or 'get_story' for different resource types, nor does it specify prerequisites or context for usage.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a retrieval operation, implying read-only behavior, but doesn't clarify permissions, rate limits, error handling, or response format. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
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, well-structured sentence with no wasted words. It front-loads the key action and resource, making it efficient and easy to parse, which is ideal for 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?
Given the tool's complexity (a read operation with one parameter), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like authentication needs, response structure, or error cases, leaving the agent under-informed for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema only shows a parameter named 'workflow_stage_id' as an integer. The description mentions 'by its ID' but doesn't add details like ID format, sourcing, or validation. It fails to compensate for the low schema coverage, providing minimal semantic value.
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 ('Retrieves') and resource ('a single workflow stage by its ID in a Storyblok space via the Management API'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_multiple_workflow_stages' or 'get_story', which would be needed for a perfect score.
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 doesn't mention prerequisites (e.g., needing a workflow stage ID), compare it to bulk retrieval tools, or specify use cases, leaving the agent without contextual usage cues.
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 are provided, so the description carries full burden. It states this is a write operation ('Adds'), implying mutation, but doesn't disclose any behavioral traits like required permissions, whether it's idempotent, error handling, rate limits, or what happens if tags already exist. For a bulk mutation tool with zero annotation coverage, this is a significant gap.
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, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the essential information about what the tool does.
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 bulk mutation tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It doesn't explain the parameter format, return values, error conditions, or behavioral constraints that would help an agent use it correctly. The conciseness comes at the expense of necessary detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'stories' as the target but provides no details about the parameter structure, required format, or how tags are specified. With 1 parameter that's completely undocumented in the schema, the description adds minimal value beyond the tool name.
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 ('Adds tags') and target resource ('multiple stories in a Storyblok space'), providing a specific verb+resource combination. However, it doesn't differentiate from potential sibling tools like 'create_tag' or 'update_story' that might also handle tags, so it doesn't reach the highest score.
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. With sibling tools like 'create_tag', 'bulk_update_stories', and 'update_story' available, there's no indication of whether this is for bulk operations only, how it differs from individual story updates, or any prerequisites for 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?
No annotations are provided, so the description carries full burden. 'Unpublishes' implies a mutation (likely destructive), but it doesn't disclose whether this requires specific permissions, if it's reversible (e.g., via 'publish_story'), what happens to the story data, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in 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 a single, clear sentence with zero wasted words. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.
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 this is a mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks crucial details like behavioral traits (e.g., reversibility, permissions), parameter meanings (especially for 'lang'), and usage context relative to siblings. The conciseness comes at the cost of necessary information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions 'by its ID', which hints at the 'story_id' parameter, but doesn't explain the 'lang' parameter at all. With 2 parameters (1 required) and no schema descriptions, the description adds minimal value beyond what's inferred from the parameter names.
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 ('unpublishes') and resource ('a Storyblok story by its ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_story' or 'bulk_unpublish_stories' (if such existed), which would require more specificity about what 'unpublish' means versus deletion.
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. With siblings like 'delete_story', 'publish_story', and 'bulk_publish_stories', it's unclear if unpublishing is reversible, if it affects multiple languages, or what prerequisites exist (e.g., story must be published first).
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but doesn't mention permission requirements, whether changes are reversible, rate limits, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 that gets straight to the point without any unnecessary words. It's appropriately sized for what it does convey, though it could benefit from additional context.
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 this is a mutation tool with 5 parameters, 0% schema description coverage, no annotations, and no output schema, the description is severely incomplete. It doesn't explain what can be updated, how to use the parameters, what permissions are needed, or what to expect in return. This leaves the agent with insufficient information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 5 parameters have descriptions in the schema. The tool description provides no information about what parameters are required, what they represent, or how they should be used. This leaves all parameters undocumented, creating a major gap for the agent.
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 ('Updates') and target resource ('an existing datasource entry in a specified Storyblok space'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'update_datasource' or 'create_datasource_entry', which would require more specificity about what distinguishes this particular update operation.
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's no mention of prerequisites (e.g., needing a datasource entry ID), when not to use it, or how it differs from similar tools like 'update_datasource' or 'bulk_update_stories'. This leaves the agent without context for proper tool selection.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation via the Management API, implying mutation, but lacks details on permissions, side effects, error handling, or response format. This is inadequate for a mutation tool with zero 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 a single, efficient sentence with no wasted words. It's appropriately sized and front-loaded, directly stating the tool's core function without unnecessary elaboration.
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 the tool's complexity (8 parameters, mutation operation), lack of annotations, 0% schema coverage, and no output schema, the description is insufficient. It doesn't provide enough context for safe and effective use, missing details on parameters, behavior, and outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 8 parameters are documented in the schema. The description provides no parameter information beyond the tool's name, failing to compensate for the coverage gap. It doesn't explain what fields can be updated or their purposes.
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 ('Updates') and resource ('an existing preset in a Storyblok space via the Management API'), providing specific verb+resource information. However, it doesn't differentiate from sibling tools like 'create_preset' or 'delete_preset' beyond the basic verb difference, missing explicit comparison.
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 is provided. The description doesn't mention prerequisites (e.g., needing an existing preset), exclusions, or comparisons to sibling tools like 'create_preset' or 'delete_preset', leaving usage context unclear.
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 are provided, so the description carries full burden. It states this is an update operation, implying mutation, but doesn't disclose behavioral traits like required permissions, whether changes are reversible, error handling, or side effects. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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, well-structured sentence with zero waste. It's front-loaded with the core purpose and avoids unnecessary elaboration. Every word earns its place, making it easy to parse quickly.
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 this is a mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks crucial context like what the tool returns, error conditions, permissions needed, or how it interacts with other tools (e.g., 'create_tag', 'delete_tag'). The agent would struggle to use this effectively without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'name of an existing tag' which hints at the 'new_name' parameter but doesn't explain 'tag_id' or provide any details on format, constraints, or examples. It adds minimal value beyond what's inferable from parameter titles.
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 ('Updates'), target resource ('name of an existing tag'), and context ('in a Storyblok space'). It distinguishes from sibling tools like 'create_tag' by specifying it updates existing tags rather than creating new ones. However, it doesn't explicitly differentiate from other update tools like 'update_internal_tag' beyond the resource name.
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 doesn't mention prerequisites (e.g., needing an existing tag ID), error conditions, or when to choose this over similar tools like 'update_internal_tag'. The agent must infer usage from the tool name and parameters alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool triggers a deployment, implying a mutation action, but fails to mention critical details like required permissions, whether the deployment is reversible, potential side effects, or rate limits. This leaves significant gaps in understanding the tool's 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 front-loaded with a clear purpose statement and uses bullet points to list parameters efficiently. Every sentence earns its place without redundancy, making it appropriately sized and well-structured for quick comprehension.
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 the complexity of a deployment tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks details on behavioral traits, error handling, and return values, which are crucial for safe and effective use, making it inadequate for the tool's 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 schema description coverage is 0%, so the description must compensate. It adds minimal semantics by briefly explaining 'branch_id' and 'release_uuids', but does not provide format details, constraints, or examples. This offers some value beyond the bare schema but is insufficient for full clarity, warranting a baseline score.
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's purpose with a specific verb ('Triggers') and resource ('deployment of specified releases to a given branch'), making it easy to understand what the tool does. However, it does not explicitly differentiate from sibling tools like 'create_release' or 'bulk_publish_stories', which might involve similar deployment or publishing actions, so it falls short of a perfect score.
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 'create_release' or 'publish_story', nor does it mention any prerequisites or exclusions. This lack of context makes it harder for an AI agent to decide when this tool is appropriate.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation operation but doesn't mention whether it requires specific permissions, if it's idempotent, what happens on conflicts, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
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 appropriately concise with two sentences that directly address the tool's purpose and parameters. The parameter documentation uses a clean format, though the lack of front-loaded differentiation from siblings slightly reduces efficiency.
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 mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is insufficient. It doesn't explain what an 'internal tag' is, how it differs from regular tags, what permissions are required, what the response contains, or potential error conditions. The agent would struggle to use this tool effectively.
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 0%, but the description provides basic parameter documentation: it explains that 'name' is required and 'object_type' is optional with possible values 'asset' or 'component'. This adds meaningful context beyond the bare schema, though it doesn't fully compensate for the complete lack of schema descriptions.
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 ('Creates a new internal tag') and resource ('in a specified Storyblok space'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_tag' or explain what distinguishes an 'internal tag' from a regular tag, which prevents a perfect score.
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 'create_tag' or 'update_internal_tag'. The description mentions the context ('in a specified Storyblok space') but doesn't specify prerequisites, permissions needed, or typical use cases, leaving the agent with insufficient context for optimal tool selection.
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?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether this requires specific permissions, if it triggers notifications, what happens to existing approvals, or what the response looks like. For a creation tool with zero annotation coverage, this is insufficient.
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 zero waste - one clear sentence stating the purpose followed by parameter documentation. Every element serves a purpose and is front-loaded appropriately.
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 creation tool with 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what a 'release approval' entails, what permissions are needed, what the result looks like, or how this interacts with other approval tools. The parameter explanations help but don't compensate for missing behavioral 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 description coverage is 0%, but the description provides param documentation that explains what each parameter represents (story ID, approver ID, release ID). It clarifies that release_id is optional, which matches the schema's required/optional structure. This adds meaningful context beyond the bare schema types.
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 ('Creates a release approval') and specifies the target resources ('for a given story and release'). It distinguishes from siblings like 'create_approval' by specifying it's for releases, but doesn't explicitly differentiate from other approval-related tools beyond the name.
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 'create_approval' or 'retrieve_multiple_approvals'. The description doesn't mention prerequisites, dependencies, or scenarios where this tool is appropriate versus other approval mechanisms.
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?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose critical behavioral traits such as whether deletion is permanent or reversible, what permissions are required, if there are confirmation prompts, rate limits, or what happens to dependent content. For a destructive operation, this is a significant gap.
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, direct sentence with no wasted words. It's front-loaded and efficiently communicates the core action without unnecessary elaboration.
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 destructive tool with no annotations, no output schema, and minimal parameter documentation, the description is inadequate. It doesn't cover safety considerations, error conditions, or result expectations, leaving the agent with insufficient context for reliable use.
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 0% description coverage, but the parameter 'id' is self-explanatory. The description doesn't add any parameter details beyond what's implied by the tool name. Since there's only one parameter, the baseline is 4, but the lack of any guidance on ID format or sourcing reduces it to 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 action ('Deletes') and resource ('an asset from Storyblok'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'delete_multiple_assets' or 'delete_asset_folder', which would require specifying this is for single assets only.
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 'delete_multiple_assets' for bulk operations or 'delete_asset_folder' for folders. The description lacks context about prerequisites, permissions, or typical use cases.
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?
With no annotations provided, the description carries full burden. It states the tool performs a deletion but doesn't disclose critical behavioral traits: whether it's destructive (implied but not explicit), requires specific permissions, has rate limits, or what happens to associated data. This leaves significant gaps for a mutation 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 efficiently structured: a clear opening sentence followed by a bullet point for the parameter. Every element serves a purpose with zero wasted words, making it easy to parse quickly.
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 destructive mutation tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks information on permissions, side effects, error conditions, or return values, which are essential for safe and effective use.
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 0%, but the description adds the parameter 'branch_id' with a brief explanation ('Numeric ID of the branch to delete'). This provides basic semantics beyond the schema's type-only definition, though it doesn't fully compensate for the coverage gap (e.g., no format examples or constraints).
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 ('Deletes') and resource ('a branch (pipeline) by its ID in a Storyblok space'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'delete_space' or 'delete_story', which would require a 5.
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 doesn't mention prerequisites (e.g., branch must exist, user permissions), consequences (e.g., irreversible deletion), or related tools like 'retrieve_single_branch' for verification.
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 are provided, so the description carries full burden. It states the tool deletes, implying a destructive mutation, but doesn't disclose critical behavioral traits: whether deletion is permanent or reversible, permission requirements, side effects (e.g., breaking references), or error conditions. For a destructive tool with zero annotation coverage, this is a significant gap.
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, direct sentence with zero waste—it states exactly what the tool does without fluff. It's appropriately sized for a simple deletion operation and front-loads the core 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 the tool's destructive nature, lack of annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't address safety concerns, return values, error handling, or dependencies. For a mutation tool that permanently removes data, more context is needed to use it correctly and safely.
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 description mentions 'by ID', which aligns with the single 'id' parameter in the schema. However, schema description coverage is 0%, so the schema provides no details about the ID format or constraints. The description adds minimal semantics (it's an ID) but doesn't explain what constitutes a valid component ID or where to obtain it, leaving important gaps.
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 ('Deletes') and the target resource ('a component by ID'), which provides a specific verb+resource combination. However, it doesn't differentiate from sibling deletion tools like delete_component_folder, delete_asset, or delete_story, which all follow the same pattern but target different resources.
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 doesn't mention prerequisites (e.g., needing the component ID), exclusions (e.g., cannot delete if in use), or related tools like delete_component_folder or update_component. The agent must infer usage from context alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool deletes a folder by ID, implying a destructive operation, but lacks critical details such as permissions required, whether deletion is permanent or reversible, rate limits, or what happens to nested content. This is a significant gap for a mutation 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 a single, efficient sentence with no wasted words. It front-loads the key action and resource, making it easy to scan and understand quickly.
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 destructive tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., permanence, side effects), parameter details, and expected outcomes, leaving the agent with insufficient context for safe and effective use.
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 description specifies that deletion is 'by its ID', which aligns with the 'folder_id' parameter in the schema. However, with 0% schema description coverage, the description doesn't add details like ID format or validation rules. It provides basic context but doesn't fully compensate for the lack of schema documentation.
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 ('Deletes') and resource ('a component folder (component group)'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'delete_component' or 'delete_asset_folder', which have similar deletion patterns but target different resources.
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. For example, it doesn't mention prerequisites (e.g., whether the folder must be empty), consequences (e.g., if components inside are also deleted), or related tools like 'delete_component' for individual items.
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 are provided, so the description carries full burden. It states this is a deletion operation, implying it's destructive, but doesn't disclose critical behavioral traits: whether deletion is permanent or reversible, what permissions are required, if there are rate limits, or what happens to associated data. For a destructive tool with zero annotation coverage, this is inadequate.
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 a single, clear sentence with no wasted words. It's appropriately sized for a simple tool, though it could be more front-loaded with critical details like the parameter. There's no fluff, making it 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 destructive tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks essential context: parameter explanation, behavioral details (permissions, reversibility), and output expectations. Given the complexity of a deletion operation in a content management system, this leaves significant gaps 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 description coverage is 0%, so the schema provides no parameter descriptions. The description doesn't mention the 'datasource_entry_id' parameter at all, nor does it explain what this ID represents or how to obtain it. However, with only 1 parameter and no schema descriptions, the baseline is 3 as the description doesn't compensate for the lack of parameter documentation.
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 ('Deletes') and target ('a datasource entry'), and specifies the context ('from a specified Storyblok space using the Management API'). It distinguishes itself from generic deletion tools by naming the specific resource type. However, it doesn't explicitly differentiate from sibling deletion tools like 'delete_datasource' or 'delete_story', which would require a 5.
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 doesn't mention prerequisites (e.g., needing a datasource entry ID), when not to use it (e.g., for bulk deletion), or refer to sibling tools like 'delete_datasource' or 'bulk_delete_stories'. Without any usage context, this is minimal 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?
With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't disclose if deletion is permanent, requires specific permissions, has side effects, or returns confirmation. For a destructive operation, this lack of transparency is a significant gap.
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 the core action, followed by a parameter note. It avoids redundancy, but the Args section could be integrated more seamlessly, and the structure is slightly fragmented.
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 destructive tool with no annotations and no output schema, the description is incomplete. It lacks critical context like deletion permanence, error conditions, or return values, making it inadequate for safe and effective use.
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 0%, but the description adds minimal param info: it names 'field_type_id' and specifies it's a numeric ID for the plugin to delete. This clarifies the parameter's role, though it doesn't detail format constraints or where to find the ID, leaving some ambiguity.
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 ('Deletes') and resource ('a field plugin by its ID'), making the purpose unambiguous. It distinguishes from siblings like 'retrieve_field_plugin' or 'update_field_plugin' by specifying deletion, but doesn't explicitly contrast with other deletion tools (e.g., 'delete_extension').
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. It doesn't mention prerequisites (e.g., permissions), consequences of deletion, or suggest related tools like 'retrieve_field_plugins' for ID lookup, leaving usage context unclear.
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?
With no annotations, the description carries full burden but provides minimal behavioral context. It states the action is destructive ('Deletes'), but doesn't cover critical aspects like irreversibility, permissions required, rate limits, error handling, or what constitutes a valid ID. This is inadequate for a mutation 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 a single, efficient sentence with no wasted words. It front-loads the core action and resource, making it easy to scan. Every element ('Deletes multiple assets', 'by numeric IDs', 'using the Storyblok Management API') contributes essential information.
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 destructive mutation tool with no annotations, 0% schema coverage, and no output schema, the description is insufficient. It lacks details on behavioral traits (e.g., permanence, auth needs), parameter constraints, error responses, and usage context, leaving the agent under-informed.
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 0%, but the description adds some value by specifying 'numeric IDs' for the 'ids' parameter, clarifying the data type beyond the schema's 'integer' array. However, it doesn't explain constraints (e.g., max array size, valid ID ranges) or provide examples, leaving gaps.
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 ('Deletes') and resource ('multiple assets'), specifying they are identified by 'numeric IDs' and using the 'Storyblok Management API'. It distinguishes from the sibling 'delete_asset' by handling multiple assets, but doesn't explicitly contrast with other bulk operations like 'bulk_delete_stories'.
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. It doesn't mention prerequisites (e.g., permissions), compare with single-asset deletion ('delete_asset') or other bulk operations, or specify scenarios where it's appropriate (e.g., batch cleanup).
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 are provided, so the description carries full burden. It states the tool uses the 'Management API' but doesn't disclose critical behavioral traits: whether deletion is permanent/reversible, required permissions, rate limits, error conditions, or what happens on success. For a destructive operation with zero annotation coverage, this is a significant gap.
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 appropriately sized with two sentences: a clear purpose statement followed by parameter clarification. It's front-loaded with the main action. However, the bullet point format for the single parameter is slightly verbose for such a simple tool, 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?
Given this is a destructive mutation tool with no annotations, no output schema, and minimal parameter documentation, the description is incomplete. It doesn't address behavioral implications, success/error responses, or integration context needed for safe operation. The agent lacks sufficient information to use this tool confidently.
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 0%, but the description adds minimal parameter semantics: it clarifies that 'preset_id' is a 'Numeric ID of the preset to delete'. This provides basic meaning beyond the schema's 'integer' type. However, it doesn't explain where to obtain this ID or format constraints, leaving gaps. With 1 parameter, baseline is 4, but incomplete compensation reduces it to 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 action ('Deletes') and resource ('a preset from a Storyblok space'), providing specific verb+resource. It distinguishes from siblings like 'create_preset' or 'update_preset' by specifying deletion. However, it doesn't explicitly differentiate from other deletion tools (e.g., 'delete_story', 'delete_asset'), which prevents a perfect score.
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 doesn't mention prerequisites (e.g., needing a preset ID), exclusions, or compare it to similar deletion tools in the sibling list. The agent must infer usage from the tool name alone.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'permanently deletes,' which implies a destructive, irreversible action, but doesn't cover critical aspects like required permissions, confirmation prompts, rate limits, or what happens to associated data (e.g., stories, assets). This is a significant gap for a high-risk mutation 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 a single, efficient sentence with zero wasted words. It's front-loaded with the key action ('permanently deletes') and resource, making it easy to scan and understand quickly.
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 destructive tool with no annotations, no output schema, and low schema coverage, the description is inadequate. It lacks details on permissions, consequences, error handling, and return values, leaving the agent with insufficient context to use it safely and effectively.
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 0% description coverage, but the description doesn't add any parameter details beyond what the schema implies (a 'space_id' is needed). It doesn't explain what a space ID is, how to obtain it, or format constraints. With one parameter, the baseline is 4, but the lack of compensation for the coverage gap lowers it to 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 action ('permanently deletes') and resource ('a Storyblok space'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'delete_story' or 'delete_asset', which would require a 5.
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 (e.g., 'delete_story' for individual stories or 'duplicate_space' for copying). It mentions the Management API but doesn't specify prerequisites, permissions, or typical scenarios for space deletion.
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 are provided, so the description carries the full burden. It states 'Deletes' which implies a destructive mutation, but doesn't disclose critical behavioral traits like whether deletion is permanent/reversible, permission requirements, side effects (e.g., on related assets), or error handling. This is a significant gap for a destructive 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 a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place in conveying the essential purpose.
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 destructive mutation tool with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It lacks behavioral context (permanence, permissions), parameter details (ID format), and output expectations. Given the complexity and risk of deletion, more completeness is needed to guide the agent safely.
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 description mentions 'by ID', which aligns with the single 'id' parameter in the schema. However, schema description coverage is 0%, so the schema provides no parameter details. The description adds minimal semantic context (it's an ID parameter) but doesn't specify format (e.g., string type, length) or validation rules, leaving the agent with incomplete guidance.
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 ('Deletes') and the resource ('a story by ID'), which provides a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'bulk_delete_stories' or 'delete_asset', which would require mentioning it's for single stories only.
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 like 'bulk_delete_stories' or 'delete_story_schedule', nor does it mention prerequisites (e.g., needing story ID) or exclusions. It's a basic statement with no contextual usage information.
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?
With no annotations provided, the description carries full burden but only states it's a deletion via an API. It doesn't disclose behavioral traits like whether the deletion is permanent, requires specific permissions, has side effects (e.g., on scheduled stories), or error handling, which is inadequate for a destructive 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 a single, efficient sentence with no wasted words, front-loaded with the core action. It's appropriately sized for a simple tool, though brevity contributes to gaps in other dimensions.
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 the tool's destructive nature, no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks critical context like behavioral risks, parameter guidance, and usage scenarios, making it insufficient for safe and effective agent use.
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 0%, but the description adds no parameter details beyond what the schema implies. It mentions 'story schedule entry' which aligns with the 'story_scheduling_id' parameter, but doesn't explain its format, source, or constraints. With 1 parameter and low coverage, this is a minimal baseline.
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 ('Deletes') and resource ('a story schedule entry'), specifying it operates via the Storyblok Management API. It distinguishes from siblings like 'delete_story' or 'bulk_delete_stories' by targeting schedule entries, but doesn't explicitly contrast with 'retrieve_one_story_schedule' or 'retrieve_multiple_story_schedules' for 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. It doesn't mention prerequisites (e.g., needing an existing schedule ID), exclusions, or sibling tools like 'update_story_schedule' or 'create_story_schedule' for related operations, leaving usage context unclear.
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 are provided, so the description carries full burden. It states 'Fetch' which implies a read operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, error handling, or what 'space' entails (e.g., metadata, permissions). For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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 extremely concise with just one sentence, front-loaded with the core action and parameter. There's no wasted text, making it easy to parse quickly, though this conciseness contributes to gaps in other dimensions.
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 the complexity (a read operation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It doesn't explain what a 'space' is, what data is returned, or how it differs from siblings. For a tool in a rich ecosystem with many alternatives, more context is needed to guide effective use.
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 0%, but the description adds minimal value by mentioning 'by ID' for the single parameter 'space_id'. However, it doesn't explain the ID format, constraints, or examples. With low coverage, the description partially compensates but not fully, aligning with the baseline expectation when schema does little work.
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 ('Fetch') and resource ('a specific space by ID'), making the purpose immediately understandable. However, it doesn't distinguish this tool from similar siblings like 'fetch_spaces' or 'retrieve_single_activity', which would require explicit differentiation to achieve a score of 5.
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. With many sibling tools like 'fetch_spaces' (likely for listing spaces) and 'retrieve_single_activity' (for other single-item retrievals), the agent lacks context on selection criteria, such as whether this is for detailed space metadata versus a summary list.
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 are provided, so the description carries the full burden. It mentions initialization and returns a URL, but doesn't disclose behavioral traits like authentication requirements, rate limits, whether it's idempotent, or what happens if parameters are invalid. For a tool with no annotations, this leaves significant gaps in understanding its 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, efficient sentence that front-loads the key action and outcome with zero waste. Every word earns its place, making it highly concise and well-structured for quick understanding.
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 no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain the return value format (e.g., URL structure, expiration), error conditions, or how it integrates with other tools like 'complete_asset_upload'. For a tool that likely involves file upload workflows, more context is needed.
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 description adds no meaning beyond the input schema, which has 0% description coverage and no parameter details. However, with 3 parameters (filename, size, content_type) that are self-explanatory to some extent, the baseline is 3 as the schema provides the structure, but the description doesn't compensate for the lack of schema descriptions.
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 ('Initializes asset upload') and the outcome ('returns signed S3 upload URL'), making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'complete_asset_upload' or 'bulk_move_assets', which might handle related asset operations, so it misses full sibling distinction.
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. For example, it doesn't mention prerequisites (e.g., needing to call this before uploading files) or when to use 'complete_asset_upload' instead. The description implies a sequence but lacks explicit usage context.
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?
With no annotations, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether this is a destructive operation (overwrites current story), requires specific permissions, has side effects (e.g., affects linked assets), or what happens on success/failure. 'Restores' implies mutation, but details are missing.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to scan and understand quickly.
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 mutation tool with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It lacks details on behavior, parameters, outcomes, and integration with sibling tools (e.g., 'get_story_versions'), leaving significant gaps for an agent to use it 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 description coverage is 0%, so the schema provides no param details. The description mentions 'story' and 'specific version', which hints at the 'id' and 'version_id' parameters, but doesn't explain their format, source, or constraints. It adds minimal meaning beyond the bare parameter names.
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 ('Restores') and the resource ('a story'), specifying it's to a 'specific version'. It distinguishes from sibling tools like 'bulk_restore_assets' by focusing on individual stories, but doesn't explicitly contrast with similar tools like 'restore_component_version'.
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. It doesn't mention prerequisites (e.g., needing story versions from 'get_story_versions'), exclusions, or how it differs from other restoration tools like 'bulk_restore_assets' or 'restore_component_version'.
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 are provided, so the description carries the full burden of behavioral disclosure. It states the action ('retrieve') but does not specify whether this is a read-only operation, what permissions are required, how results are formatted (e.g., pagination, error handling), or any rate limits. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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, clear sentence with no wasted words, making it highly concise and front-loaded. It efficiently communicates the core action without unnecessary elaboration.
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 the lack of annotations, no output schema, and low schema description coverage, the description is incomplete. It does not address behavioral aspects like safety, permissions, or result format, which are crucial for an agent to use the tool correctly in a real-world 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 has 1 parameter with 0% description coverage, and the tool description does not add any details about the 'space_id' parameter (e.g., what constitutes a valid space ID, where to find it, or format constraints). Since the schema coverage is low, the description fails to compensate, but with only one parameter, the baseline is slightly higher than minimal.
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 ('retrieve') and resource ('settings for all extensions installed in a space'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'retrieve_extension_settings' or 'retrieve_all_extensions', which could cause confusion about scope.
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 'retrieve_extension_settings' (which might retrieve settings for a single extension) or 'retrieve_all_extensions' (which might list extensions without settings). There is no mention of prerequisites, exclusions, or specific contexts for usage.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'Retrieves comments,' implying a read-only operation, but doesn't specify if it requires authentication, has rate limits, returns paginated results, or handles errors. This leaves significant gaps in understanding how the tool behaves in practice, making it less transparent for safe and effective use.
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 appropriately sized and front-loaded, with the core purpose stated in the first sentence and a bullet point for the parameter. There is no wasted text, and every element adds value, making it efficient and easy to parse for an AI agent.
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 the tool's moderate complexity (retrieving comments for a discussion), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like authentication needs, error handling, or return format, and it lacks usage guidelines. This makes it inadequate for an AI agent to use the tool confidently in varied contexts.
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 1 parameter with 0% description coverage, and the description adds meaning by explaining that 'discussion_uuid' is the 'UUID of the discussion in the idea.' This clarifies the parameter's purpose beyond the schema's basic type. However, it doesn't provide additional details like format examples or constraints, so it meets the baseline for minimal compensation without fully enriching the 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 verb ('Retrieves') and resource ('comments for a specific idea discussion in a Storyblok space'), making the purpose understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'retrieve_multiple_comments' or 'retrieve_specific_discussion', which could handle similar comment or discussion retrieval, leaving some ambiguity about when to choose this specific tool.
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 'retrieve_multiple_comments' for broader comment retrieval or 'retrieve_specific_discussion' for discussion details. It lacks context on prerequisites, like needing a valid discussion UUID, or exclusions, such as not supporting filtering or pagination, which limits its utility for an AI agent.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('retrieves') but lacks details on permissions, rate limits, pagination, or response format. For a retrieval tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves operationally.
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 appropriately sized and front-loaded with the main purpose, followed by bullet points for parameters. Every sentence adds value without redundancy, making it efficient and easy to scan.
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 moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and parameters but lacks details on usage context, behavioral traits, and output, which are necessary for full understanding in this environment.
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 description adds meaning by explaining that 'by_object_type' filters tags as 'asset' or 'component' and 'search' is for substring matching in tag names. With 0% schema description coverage, this compensates somewhat, but it doesn't cover default behaviors or constraints beyond basic usage, leaving room for improvement.
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 ('retrieves') and resource ('internal tags (asset/component) from a specified Storyblok space'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_multiple_tags' or 'retrieve_single_activity', which might have overlapping retrieval functions but for different resources or scopes.
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 mentions filtering by object type and search, but doesn't specify prerequisites, context, or exclusions, such as whether it requires specific permissions or how it relates to other tag-related tools in the sibling list.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a retrieval operation via the Management API, implying read-only behavior, but lacks details on permissions, rate limits, pagination, error handling, or response format. This is inadequate for a tool with potential complexity.
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 structured with a clear main sentence and a bullet point for parameter details. It avoids unnecessary words, though it could be slightly more front-loaded by integrating the parameter hint into the main flow for optimal efficiency.
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 the complexity of a retrieval tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It lacks critical details like response structure, error cases, authentication needs, and full parameter explanations, making it insufficient for reliable agent use.
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 0%, so the schema provides no parameter descriptions. The description adds minimal semantics by explaining 'by_status' as an optional filter with specific values, but doesn't cover 'space_id' or provide deeper context like format or constraints. This partial compensation earns a baseline score.
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 ('Retrieves') and resource ('multiple story scheduling entries in a Storyblok space via the Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_one_story_schedule' or 'fetch_stories', which would be needed for a perfect score.
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 mentions an optional status filter but doesn't explain when to apply it or compare it to similar retrieval tools in the sibling list, leaving the agent without usage context.
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 are provided, so the description carries the full burden. It mentions retrieval via the Management API and optional filtering, but it doesn't disclose critical behavioral traits such as whether this is a read-only operation, potential rate limits, authentication requirements, pagination behavior, or what the return format looks like. For a retrieval tool with zero annotation coverage, this is a significant gap.
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 appropriately sized with two sentences that are front-loaded and waste-free. The first sentence states the core purpose, and the second adds optional functionality, making it efficient and easy to parse.
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 the complexity of retrieving multiple workflows, no annotations, no output schema, and low schema description coverage, the description is incomplete. It lacks details on behavioral aspects (e.g., safety, rate limits), output format, and comprehensive usage guidelines, making it inadequate for informed tool selection and 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?
The description adds meaning by explaining that the 'content_type' parameter is used for optional filtering (e.g., 'page', 'article'), which clarifies its purpose beyond the schema's generic title. However, with 0% schema description coverage and only one parameter, the description compensates somewhat but doesn't provide full details like allowed values or examples. The baseline is adjusted since it adds some value.
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 ('Retrieves') and resource ('all workflows in a Storyblok space via the Management API'), making the purpose specific and understandable. However, it doesn't explicitly distinguish itself from sibling tools like 'retrieve_single_workflow' or 'fetch_stories', which could provide similar retrieval functions for different resources.
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 mentions optional filtering by content type, which implies usage when such filtering is needed, but it doesn't provide explicit guidance on when to use this tool versus alternatives (e.g., 'retrieve_single_workflow' for a specific workflow or 'fetch_stories' for stories). No exclusions or prerequisites are stated.
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 are provided, so the description carries full burden. It states it's a retrieval operation, implying read-only behavior, but doesn't disclose any behavioral traits like authentication requirements, rate limits, error handling, or what the return format looks like (especially important since there's no output schema). This leaves significant gaps for an agent to understand how to properly invoke 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 appropriately concise with two sentences: one stating the purpose and one explaining the parameter. It's front-loaded with the main action. There's no wasted text, though it could be slightly more structured (e.g., bullet points for clarity).
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 the complexity (a read operation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It doesn't explain what a 'story schedule entry' contains, how results are returned, or any error conditions. For a tool that retrieves data, the lack of output details is a significant gap, making it hard for an agent to use effectively.
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 description adds minimal parameter semantics: it explains that 'story_scheduling_id' is the 'Numeric ID of the schedule to retrieve'. With 0% schema description coverage and 1 parameter, this provides basic meaning beyond the schema's type information. However, it doesn't specify format constraints, valid ranges, or where to obtain this ID, leaving room for improvement.
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 ('Retrieves') and resource ('a single story schedule entry') with specific context ('by its ID in a Storyblok space via the Management API'). It distinguishes from sibling tools like 'retrieve_multiple_story_schedules' by specifying 'single', but doesn't explicitly mention other retrieval alternatives like 'get_story' or 'retrieve_story_schedule' (which doesn't exist in the list).
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 doesn't mention sibling tools like 'retrieve_multiple_story_schedules' for bulk operations or 'get_story' for different data types, nor does it specify prerequisites or appropriate contexts beyond the basic action.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions retrieval but does not specify whether this is a read-only operation, if it requires authentication, potential rate limits, error handling, or what the output looks like. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
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, clear sentence with no unnecessary words, making it highly concise and front-loaded. It efficiently communicates the core functionality without redundancy or fluff, earning a top score for brevity and structure.
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 the lack of annotations, no output schema, and low schema description coverage, the description is incomplete. It fails to address key contextual aspects such as authentication needs, error responses, or how the activity log is structured, leaving the agent with insufficient information for reliable tool invocation in a complex environment.
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 description coverage is 0%, with one parameter ('activity_id') documented only by title and type in the schema. The description adds minimal semantics by specifying that it retrieves 'by its ID', but does not explain the ID format, source, or constraints. This provides some value over the bare schema, but not enough to fully compensate for the low coverage.
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 ('retrieves') and resource ('a single activity log by its ID from a specified Storyblok space'), making the purpose understandable. However, it does not explicitly differentiate from sibling tools like 'retrieve_multiple_activities', which is a similar retrieval operation but for multiple items, leaving some ambiguity about when to choose one over the other.
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 'retrieve_multiple_activities' for batch retrieval or other retrieval tools in the sibling list. It lacks context on prerequisites, error conditions, or specific use cases, offering only a basic functional statement without usage instructions.
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 are provided, so the description carries the full burden. It states 'retrieves' implying a read operation, but doesn't disclose behavioral traits like whether it requires authentication, rate limits, error handling (e.g., for invalid IDs), or the return format. This leaves significant gaps for a tool with no 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 a single, well-structured sentence with zero waste. It front-loads the key action ('retrieves') and resource, making it efficient and easy to parse.
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 the lack of annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what the tool returns, error conditions, or usage context, leaving the agent with insufficient information to invoke it correctly beyond the basic parameter.
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 description coverage is 0%, but the description mentions 'by its ID', which aligns with the 'approval_id' parameter in the schema. However, it doesn't add meaning beyond this basic mapping—no details on ID format, validation, or examples. With one parameter and low schema coverage, this provides minimal compensation.
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 ('retrieves') and resource ('a single approval by its ID from a specified Storyblok space'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'retrieve_multiple_approvals' or 'get_story', which also retrieve data, so it misses full sibling distinction.
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 doesn't mention prerequisites (e.g., needing a valid approval ID), compare it to 'retrieve_multiple_approvals' for bulk operations, or specify contexts where this single-retrieval is preferred.
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 are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves by ID, implying a read-only operation, but fails to describe critical behaviors such as error handling (e.g., what happens if the ID is invalid), response format, authentication requirements, or rate limits. This leaves significant gaps in understanding how the tool behaves.
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, well-structured sentence with no wasted words. It front-loads the key action and resource, making it easy to parse quickly, which is ideal for 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?
Given the tool's simplicity (one parameter) but lack of annotations and output schema, the description is incomplete. It does not cover behavioral aspects like error handling or response details, and while it addresses the parameter, it lacks depth. For a retrieval tool with no structured support, more context is needed to be fully helpful.
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 description mentions the parameter 'folder_id' and its purpose ('by its ID'), which adds semantic meaning beyond the schema's 0% coverage. However, it does not elaborate on the ID format, constraints, or examples, providing only basic context. With one parameter and low schema coverage, this is adequate but minimal.
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 ('Retrieves') and resource ('a single component folder (component group)'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'fetch_component_folders' (which likely retrieves multiple folders) or 'get_component' (which retrieves a component, not a folder), leaving room for ambiguity in sibling distinction.
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 mention prerequisites (e.g., needing a valid folder ID), compare it to similar tools like 'fetch_component_folders', or specify use cases, leaving the agent without contextual usage instructions.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a retrieval operation, implying read-only behavior, but doesn't clarify aspects like authentication needs, rate limits, error handling, or what the return format looks like. This leaves significant gaps for a tool that fetches data.
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, clear sentence with no wasted words, making it easy to parse and understand quickly. It's front-loaded with the core action and resource, which is ideal for 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?
Given the complexity of a retrieval tool with no annotations, 0% schema description coverage, and no output schema, the description is insufficient. It doesn't explain what a datasource is, how results are formatted, or any behavioral traits, leaving the agent with inadequate information to use the tool effectively.
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 description mentions retrieving from 'a specified Storyblok space,' which implies a context for the datasource_id parameter, but the schema has 0% description coverage and only documents 'datasource_id' as an integer without further details. The description adds minimal value beyond the schema, so it meets the baseline for adequate but incomplete parameter information.
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 ('Retrieves') and resource ('a single datasource from a specified Storyblok space'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'retrieve_multiple_datasources' or 'get_component', which might have overlapping retrieval functions, preventing a perfect score.
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 'retrieve_multiple_datasources' for bulk operations or 'get_component' for other resource types. It lacks context about prerequisites or specific scenarios, leaving the agent to infer usage based on the tool name alone.
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 are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves data, implying a read-only operation, but doesn't specify if it requires authentication, has rate limits, returns structured data, or handles errors. For a tool with zero annotation coverage, this lack of behavioral details is a significant gap.
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, efficient sentence with no wasted words, clearly front-loading the core action. It's appropriately sized for a simple retrieval tool, making it easy to parse quickly.
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 the tool's simplicity (1 parameter) but lack of annotations and output schema, the description is incomplete. It doesn't explain the return format (e.g., JSON object with release details), error handling, or authentication needs, which are crucial for an agent to use it effectively in a no-annotation environment.
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 description mentions retrieving from 'a specified Storyblok space,' which hints at a context parameter, but the input schema only includes 'release_id' with 0% coverage. Since schema description coverage is low (0%), the description doesn't compensate by explaining what 'release_id' represents (e.g., numeric ID, format, or source), leaving parameters partially undocumented.
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 ('retrieves') and resource ('a single release from a specified Storyblok space'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'retrieve_multiple_releases' or 'get_story', which might retrieve similar content, leaving room for ambiguity about when to choose this specific retrieval tool.
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 doesn't mention prerequisites (e.g., needing a specific space), exclusions, or comparisons to sibling tools like 'retrieve_multiple_releases' for batch operations or 'get_story' for different content types, leaving the agent without usage context.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a retrieval operation but doesn't mention whether it's read-only, what permissions are needed, error handling, or response format. This leaves significant gaps for a tool with no 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately brief with two sentences that get straight to the point. The bullet point format for the parameter is efficient. However, the second sentence could be integrated more smoothly rather than as a separate bullet.
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 retrieval tool with no annotations, no output schema, and minimal parameter documentation, the description is inadequate. It should explain what information is returned, error conditions, authentication requirements, and how this differs from similar retrieval tools in the sibling list.
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 description adds the parameter 'discussion_id' with a brief explanation ('Numeric ID of the discussion'), which provides basic semantics. However, with 0% schema description coverage and only one parameter documented, this is the minimum viable baseline - it adds some value but doesn't fully compensate for the schema's lack of descriptions.
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 ('retrieves') and resource ('a specific discussion by its ID in a Storyblok space'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_multiple_discussions' or 'retrieve_my_discussions', which would require a 5.
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 'retrieve_multiple_discussions' or 'retrieve_my_discussions'. The description only states what it does, not when it's appropriate or what prerequisites might exist.
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?
With no annotations, the description carries full burden but lacks behavioral details. It states it's an update operation, implying mutation, but doesn't disclose permissions needed, rate limits, side effects (e.g., if it overwrites existing data), or response format. This is inadequate for a mutation tool with zero 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. It uses bullet points for parameters, which is efficient, though some sentences could be more streamlined (e.g., 'Required:' section is slightly redundant with schema).
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 the complexity (mutation tool with 4 parameters, 0% schema coverage, no output schema, and no annotations), the description is incomplete. It covers basic parameters but lacks critical context like behavioral traits, usage scenarios, or output expectations, making it insufficient for safe and effective use.
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 0%, but the description adds value by explaining parameters: it clarifies 'discussion_id' and 'comment_id' as numeric IDs, and describes 'message_json' and 'message' payload details. However, it doesn't fully compensate for the coverage gap (e.g., missing details on 'message_json' object structure or validation rules).
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 ('Updates') and resource ('a comment in a discussion'), specifying it uses the Storyblok Management API. It distinguishes from siblings like 'create_comment' by focusing on updates, but doesn't explicitly differentiate from other update tools (e.g., 'update_story').
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 is provided. It doesn't mention prerequisites (e.g., authentication), when not to use it, or compare with similar tools like 'update_story' or 'create_comment' from the sibling list.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation but doesn't mention required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool, this leaves significant gaps in understanding its 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 perfectly concise with zero wasted words. It starts with the core purpose, then lists parameters with brief explanations in a clean, structured format. Every sentence 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?
For a mutation tool with no annotations, no output schema, and incomplete parameter documentation (schema coverage is 0%), the description is inadequate. It doesn't explain what the tool returns, error conditions, or behavioral constraints, leaving the agent with insufficient context for reliable use.
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 description lists all three parameters with brief explanations, adding value beyond the schema which has 0% description coverage. However, it doesn't clarify parameter interactions (e.g., what happens if only one optional parameter is provided) or provide examples, leaving some ambiguity.
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 ('Updates') and resource ('an internal tag (asset/component) in a specified Storyblok space'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its sibling 'update_tag' or other update tools, which prevents a perfect score.
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 like 'update_tag' or 'create_internal_tag', nor does it mention any prerequisites or constraints. The agent must infer usage from the tool name alone.
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 are provided, so the description carries full burden. It states it's an update operation via an API, implying mutation, but lacks details on permissions, side effects (e.g., if it overwrites other fields), rate limits, or response format. This is a significant gap for a mutation tool with zero 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose, followed by a bulleted list of parameters. Each sentence earns its place, though the bullet points could be more integrated into the narrative flow.
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 the complexity (mutation tool with 4 parameters), no annotations, and no output schema, the description is incomplete. It lacks behavioral details (e.g., error handling, permissions), output information, and full parameter guidance, making it inadequate for safe and effective use.
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 0%, so the description must compensate. It lists all 4 parameters with brief explanations (e.g., 'Numeric ID of the schedule to update'), adding meaning beyond the schema's titles. However, it doesn't cover parameter constraints (e.g., format for 'publish_at' beyond 'ISO-8601 UTC'), leaving some gaps.
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 ('Updates') and resource ('an existing story schedule'), specifying it's for the Storyblok Management API. It distinguishes from sibling tools like 'create_story_schedule' by focusing on updates, though it doesn't explicitly contrast with other update tools (e.g., 'update_story').
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 'update_story' or 'create_story_schedule'. The description mentions it updates an existing schedule but doesn't specify prerequisites (e.g., needing an existing schedule ID) or exclusions, leaving usage context implied.
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 are provided, so the description carries the full burden. It states the tool deletes an access token, implying a destructive mutation, but fails to disclose critical behavioral traits like required permissions, whether the deletion is permanent or reversible, rate limits, or any side effects. This is a significant gap for a destructive 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?
The description is appropriately sized and front-loaded, starting with the core action and resource. The param and return sections are structured but slightly verbose; the return statement could be more precise (e.g., specifying success/error conditions). Overall, it's efficient with minimal waste.
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 the tool's destructive nature, no annotations, and no output schema, the description is incomplete. It lacks details on behavioral context (e.g., permissions, irreversibility), usage guidelines, and output specifics. For a mutation tool with such risks, this leaves the agent under-informed.
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 description adds meaningful semantics for the single parameter 'token_id' by explaining it's 'The ID of the access token to delete,' which clarifies its purpose beyond the schema's basic type (integer). With 0% schema description coverage and only one parameter, this compensation is effective, though it could note format constraints (e.g., where to find the ID).
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 ('Delete') and resource ('an access token from the current Storyblok space using the Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'delete_space_role' or 'delete_webhook', which also delete resources, so it doesn't fully distinguish itself in 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?
The description provides no guidance on when to use this tool versus alternatives, such as other deletion tools in the sibling list (e.g., 'delete_space', 'delete_webhook'). It lacks context about prerequisites, permissions, or scenarios where this deletion is appropriate, leaving the agent with no usage direction.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves logs but doesn't mention critical aspects like whether it's a read-only operation, potential rate limits, authentication needs, pagination behavior, or error handling. The description is minimal and fails to provide necessary operational context for safe and effective use.
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 well-structured and concise, with a clear purpose statement followed by a bulleted list of optional filters. Each sentence earns its place by providing essential information without redundancy. It could be slightly improved by front-loading more critical details, but overall, it's efficient and easy to parse.
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 the complexity of a retrieval tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., read-only nature, pagination), error conditions, and output format. While it covers parameters well, the overall context is insufficient for an AI agent to use the tool confidently without additional assumptions.
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 description adds significant value beyond the input schema, which has 0% description coverage. It explains the purpose of each optional filter (e.g., 'created_at_gte / created_at_lte: YYYY-MM-DD date strings') and provides examples for 'types'. This clarifies parameter usage effectively, compensating for the schema's lack of descriptions, though it doesn't cover all potential nuances like format constraints beyond dates.
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's purpose: 'Retrieves activity logs for a specified Storyblok space.' It specifies the verb ('retrieves'), resource ('activity logs'), and context ('Storyblok space'), making the intent unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_single_activity' or other retrieval tools, which prevents a perfect score.
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 lists optional filters but doesn't mention prerequisites, such as whether a space ID is required (implied but not stated), or compare it to siblings like 'retrieve_single_activity' for single logs. This lack of contextual usage advice limits its effectiveness for an AI agent.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the API source ('Storyblok Management API') but lacks details on permissions, rate limits, pagination, or what 'all comments' entails (e.g., format, limits). This is insufficient for a retrieval tool with zero 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the main purpose, followed by a bullet point for the parameter. It avoids unnecessary fluff, but the bullet point formatting is slightly informal and could be integrated more smoothly into a single sentence.
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 the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'retrieves all comments' returns (e.g., list structure, fields), potential errors, or usage constraints like authentication needs. For a tool with one parameter but no structured support, this leaves 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?
The description adds meaningful context for the single parameter by explaining that 'discussion_id' is a 'Numeric ID of the discussion'. Since schema description coverage is 0% (no schema descriptions) and there's only one parameter, this compensates well, though it could specify format constraints (e.g., positive integer).
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 ('retrieves all comments') and resource ('from a specific discussion via the Storyblok Management API'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_idea_discussions_comments' or 'retrieve_specific_discussion', which could cause confusion about scope.
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. For example, it doesn't mention when to choose this over 'retrieve_idea_discussions_comments' or if it's for a specific type of discussion. The description only states what it does, not when it's appropriate.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool retrieves data via an API but doesn't specify whether it's read-only, requires authentication, has rate limits, or describes the return format (e.g., pagination, error handling). This leaves significant gaps for a tool with multiple parameters.
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 well-structured with a clear opening sentence followed by a bulleted list of parameters, making it easy to scan. It's appropriately sized without unnecessary fluff, though the bullet points could be more integrated into the flow for slightly better structure.
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 the tool's complexity (4 parameters, no annotations, no output schema), the description is incomplete. It covers parameter purposes but lacks behavioral details (e.g., safety, response format) and usage guidelines, making it insufficient for an agent to fully understand how to invoke and interpret results.
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 description adds meaningful context for all four parameters by explaining their purposes (e.g., 'exclude_id: ID of a workflow stage to exclude', 'search: Filter by workflow stage name'), which compensates for the 0% schema description coverage. However, it doesn't provide examples or format details (e.g., for 'by_ids'), keeping it from a perfect score.
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 ('Retrieves') and resource ('multiple workflow stages in a Storyblok space via the Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_single_workflow_stage' or 'retrieve_multiple_workflows', which would be needed for a perfect score.
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 'retrieve_single_workflow_stage' or 'retrieve_multiple_workflows'. It lists parameters but doesn't explain usage context, prerequisites, or exclusions, leaving the agent to infer when this tool is appropriate.
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 are provided, so the description carries the full burden of behavioral disclosure. It mentions validation but does not describe what happens during validation (e.g., returns errors, success status), whether it's read-only or has side effects, authentication needs, or rate limits. For a tool with 4 parameters and no annotations, this is a significant gap in transparency, leaving the agent with insufficient information about the tool's 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 appropriately sized and front-loaded: the first sentence states the core purpose, and the second sentence provides key usage details. There is no wasted text, and both sentences earn their place by adding essential information. It is concise and well-structured for quick comprehension.
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 the complexity (4 parameters, no annotations, no output schema), the description is incomplete. It covers the basic purpose and two parameters but misses details on 'component_name' and 'space_id', behavioral traits, and output expectations. For a validation tool with multiple inputs and no structured guidance, more context is needed to ensure the agent can use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description adds some semantics by explaining that 'story_id' is used 'to fetch' and 'story_content' can be provided 'directly,' which clarifies the purpose of two parameters. However, it does not mention 'component_name' (the only required parameter) or 'space_id', leaving half of the parameters undocumented. The description partially compensates but does not fully address the coverage gap.
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's purpose: 'Validates a story's content against a component schema.' It specifies the verb ('validates'), resource ('story's content'), and target ('component schema'), making the intent unambiguous. However, it does not explicitly differentiate from sibling tools like 'compare_story_versions' or 'debug_story_access', which might involve similar content analysis, so it lacks sibling differentiation.
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 implied usage guidance by stating 'Either provide story_id (to fetch) or story_content directly,' which indicates the two primary ways to use the tool. However, it does not specify when to choose this tool over alternatives (e.g., vs. 'compare_story_versions' for validation-like checks) or any prerequisites (e.g., requiring a valid component schema). The guidance is functional but lacks explicit context or exclusions.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'Adds a comment' (implying a write/mutation operation) but doesn't cover critical aspects like required permissions, rate limits, whether the operation is idempotent, or what happens on success/failure. This leaves significant gaps for an agent to understand the tool's 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?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The bullet points efficiently detail parameters without redundancy. However, the formatting with quotes and indentation slightly reduces structural clarity.
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 complexity (mutation with 3 parameters), lack of annotations, and no output schema, the description is moderately complete. It covers parameter semantics well but lacks behavioral details (e.g., response format, error handling) and usage guidelines, leaving room for improvement in helping an agent use it 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?
The description adds meaningful context for all three parameters beyond the input schema, which has 0% description coverage. It clarifies that 'discussion_id' is numeric, 'message_json' is a required array with specific object structure ('type', 'text', 'attrs'), and 'message' is optional plain text. This compensates well for the schema's lack of descriptions.
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 ('Adds a comment') and resource ('to a discussion via the Storyblok Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'create_discussion' or 'update_comment', which would be needed for a perfect score.
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 lacks context about prerequisites (e.g., needing an existing discussion), exclusions, or comparisons to related tools like 'create_discussion' for starting discussions or 'update_comment' for modifying existing comments.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a new discussion, implying a write operation, but lacks details on permissions, side effects (e.g., whether it triggers notifications), error handling, or response format. This leaves significant gaps in understanding the tool's behavior beyond the basic action.
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 efficiently structured with a clear purpose statement followed by a bulleted list of parameters, making it easy to scan. It avoids unnecessary fluff, though the parameter explanations are brief and could be more detailed without sacrificing conciseness.
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 complexity of a 7-parameter write operation with no annotations and no output schema, the description is moderately complete. It covers the purpose and parameters but lacks behavioral context, error information, and output details, making it adequate for basic use but insufficient for full understanding in a production setting.
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 description adds substantial value by listing all 7 required parameters with brief explanations (e.g., 'ID of the story' for story_id) and an example for message_json. Since schema description coverage is 0%, this compensates well, providing clear semantics that the schema alone does not, though it could benefit from more detail on formats or constraints.
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 ('Creates a new discussion') and target resource ('for a story via the Storyblok Management API'), which is specific and actionable. However, it does not explicitly differentiate from sibling tools like 'create_comment' or 'resolve_discussion', which might handle similar discussion-related operations, leaving room for ambiguity in sibling 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?
The description provides no guidance on when to use this tool versus alternatives, such as 'create_comment' or 'retrieve_multiple_discussions', nor does it mention prerequisites, exclusions, or specific contexts. It simply lists required parameters without contextual usage instructions.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it 'creates' (implying a write/mutation operation) but doesn't mention required permissions, rate limits, whether the schedule is reversible, what happens on success/failure, or if it triggers notifications. The ISO-8601 format hint is useful but insufficient for a mutation tool with zero 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with a clear opening sentence followed by bullet points for parameters. Every element earns its place: the API context is relevant, and parameter explanations are necessary given the 0% schema coverage. Could be slightly more front-loaded with key behavioral information.
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 mutation tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description provides adequate parameter semantics but lacks critical behavioral context. It doesn't explain what a 'story schedule' actually does (e.g., auto-publishes at specified time), success/failure responses, or error conditions. The parameter explanations partially compensate for schema 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 0%, so the description must compensate. It provides clear semantic explanations for all 3 parameters: story_id as 'Numeric ID of the story to be scheduled', publish_at with format example, and language as optional with code examples. This adds significant value beyond the bare schema, though it doesn't cover validation rules or error cases.
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 ('Creates') and resource ('new story schedule') with specific context ('via the Storyblok Management API'). It distinguishes from obvious siblings like 'create_story' or 'update_story_schedule' by focusing on scheduling. However, it doesn't explicitly differentiate from 'bulk_create_stories' or 'publish_story' which might have overlapping scheduling functionality.
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 doesn't mention prerequisites (e.g., story must exist), when scheduling is appropriate versus immediate publishing, or how it relates to siblings like 'publish_story', 'bulk_publish_stories', or 'update_story_schedule'. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool performs a deletion but doesn't disclose behavioral traits like whether this is irreversible, requires specific permissions, affects related data, or has rate limits. The description is minimal and lacks critical context for a destructive 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 appropriately sized and front-loaded, with the core purpose in the first sentence and parameter details in the second. There's no wasted text, and it follows a clear structure (general action followed by specific parameter).
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 the tool's destructive nature, lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral risks, success/error responses, or integration with sibling tools (e.g., how to obtain approval IDs). For a deletion tool with zero annotation coverage, this leaves significant gaps for an AI 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?
The description adds meaningful semantics for the single parameter ('approval_id: Numeric ID of the approval to delete'), clarifying its purpose beyond the schema's basic type (integer). With 0% schema description coverage and only one parameter, this compensates adequately, though it could specify format constraints (e.g., positive integer).
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 ('Deletes') and resource ('an approval from a specified Storyblok space'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'delete_release_approval' or 'delete_access_token', which target different resources but share the 'delete' verb pattern.
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 doesn't mention prerequisites (e.g., needing an approval ID from 'retrieve_single_approval'), exclusions, or compare it to similar deletion tools in the sibling list. The agent must infer usage from the tool name alone.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a deletion operation via the Storyblok Management API, implying it's destructive and requires API access. However, it doesn't mention whether deletion is permanent/reversible, what permissions are needed, rate limits, error conditions, or what the response looks like. For a destructive tool with zero annotation coverage, this is a significant gap.
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 efficiently structured with a clear purpose statement followed by bullet-point parameter explanations. Every sentence earns its place, though the bullet points could be integrated more smoothly. It's appropriately sized for a simple 2-parameter tool.
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 destructive deletion tool with 2 parameters, no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and parameters but lacks critical context about behavioral traits (permanence, permissions), usage guidelines, and expected outcomes. The parameter explanations help, but overall completeness is limited given the tool's potential impact.
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 description explicitly lists both parameters (discussion_id and comment_id) with brief explanations ('Numeric ID of the discussion', 'Numeric ID of the comment'), adding clear meaning beyond the schema's basic type definitions. With 0% schema description coverage, this fully compensates for the schema's lack of parameter descriptions, though it doesn't provide format examples or validation rules.
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 ('Deletes a comment') and resource ('from a discussion via the Storyblok Management API'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from other deletion tools like delete_story or delete_asset, which would be needed for a perfect score.
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's no mention of prerequisites (like needing specific permissions), what happens after deletion, or how this differs from similar tools like delete_story or delete_comment's sibling create_comment. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a deletion operation, implying it's destructive, but doesn't specify whether the deletion is permanent, reversible, requires specific permissions, or has side effects (e.g., on associated assets/components). This is inadequate for a destructive tool with zero 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 efficiently structured in two sentences: the first states the tool's purpose clearly, and the second explains the parameter. There's no wasted text, and the information is front-loaded with the core 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?
For a destructive deletion tool with no annotations and no output schema, the description is insufficient. It doesn't cover behavioral aspects like permanence, permissions, or error conditions, nor does it explain what the tool returns (e.g., success confirmation or error details). Given the complexity and risk of deletion operations, more context is needed.
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 description explicitly documents the single parameter ('internal_tag_id') with its purpose ('Numeric ID of the internal tag to delete'), which adds crucial meaning beyond the schema's minimal coverage (0%). Since there's only one parameter and the description fully explains it, this compensates well for the schema's lack of descriptions.
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 ('Deletes') and resource ('an internal tag (asset/component) in a specified Storyblok space'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_tag' or 'delete_internal_tag' (if both existed), which would require more specific context about what distinguishes internal tags from regular tags.
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 doesn't mention prerequisites (e.g., needing an existing internal tag ID), what happens after deletion, or how it differs from other deletion tools in the sibling list like 'delete_tag' or 'delete_asset'.
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 are provided, so the description carries full burden. 'Retrieve' implies a read operation, but it doesn't disclose behavioral traits like pagination, rate limits, sorting, what 'accessible' means (e.g., based on permissions), or the response format. For a list operation with zero annotation coverage, this is a significant gap in transparency.
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, efficient sentence with no wasted words. It's front-loaded with the core action ('Retrieve all accessible spaces') and avoids unnecessary elaboration. Every word earns its place, making it highly concise and well-structured.
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 the complexity (a list operation with no output schema and no annotations), the description is incomplete. It lacks details on return values (e.g., list format, fields included), pagination, error handling, or what 'accessible' entails. Without annotations or output schema, the description should provide more context for effective use.
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 tool has 0 parameters with 100% schema description coverage (empty schema). The description doesn't need to compensate for missing parameter documentation. It appropriately doesn't mention parameters, aligning with the schema. Baseline is 4 for zero parameters, as there's nothing to add 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 'Retrieve all accessible spaces' clearly states the verb ('retrieve') and resource ('spaces'), with 'all accessible' providing scope. It distinguishes from siblings like 'get_space' (singular) and 'duplicate_space' (copy operation). However, it doesn't explicitly differentiate from other list/retrieve tools like 'fetch_stories' or 'fetch_assets' beyond the resource name.
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 doesn't mention prerequisites (e.g., authentication), when not to use it (e.g., for single space details), or direct alternatives like 'get_space' for specific spaces. The agent must infer usage from the tool name alone.
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 are provided, so the description carries full burden. It states 'Marks a discussion as resolved,' implying a mutation, but lacks details on permissions, side effects (e.g., notifications), reversibility, or error handling. This is inadequate for a mutation tool with zero 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by parameter details in a bulleted list. It's efficient with minimal waste, though the parameter explanations could be slightly more detailed (e.g., clarifying if solved_at is optional).
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 mutation tool with no annotations and no output schema, the description covers the basic action and parameters but lacks behavioral context (e.g., effects, permissions). It's minimally viable but has clear gaps in usage guidance and transparency.
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 0%, but the description explicitly lists both parameters with brief semantics: 'discussion_id: Numeric ID of the discussion' and 'solved_at: Timestamp when the discussion is resolved (ISO 8601 format).' This adds meaningful context beyond the schema's basic types, compensating for the coverage gap.
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 ('Marks a discussion as resolved') and the target resource ('discussion'), with specific context ('via the Storyblok Management API'). However, it doesn't explicitly differentiate from sibling tools like 'create_discussion' or 'retrieve_specific_discussion' beyond the verb 'resolve'.
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 doesn't mention prerequisites (e.g., needing an existing discussion), exclusions, or related tools like 'update_discussion' (if it exists) for partial updates.
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 are provided, so the description carries the full burden of behavioral disclosure. It states it's a retrieval operation, implying read-only behavior, but doesn't mention authentication requirements, rate limits, error conditions, or what happens if the ID doesn't exist. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. The Args section is structured but could be more integrated. There's minimal waste, though it could be slightly more polished in flow.
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 no annotations and no output schema, the description provides basic purpose and parameter semantics but lacks behavioral details like error handling or return format. It's adequate for a simple retrieval tool but incomplete for full agent understanding without additional context.
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 0%, so the description must compensate. It provides clear meaning for both parameters: 'field_type_id' is explained as 'Numeric ID of the field plugin', and 'context' is clarified with allowed values ('space', 'org', or 'partner') and a default ('space') implied in the schema. This adds substantial value beyond the bare 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 ('retrieves'), resource ('a single field plugin'), and key identifier ('by its ID in the specified context'). It distinguishes from sibling tools like 'retrieve_field_plugins' (plural) which likely retrieves multiple plugins. However, it doesn't explicitly contrast with other retrieval tools like 'retrieve_extension' or 'retrieve_component'.
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 versus alternatives is provided. The description doesn't mention prerequisites, permissions, or scenarios where this tool is preferred over other retrieval methods. It only states what it does, not when to use it.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool retrieves data and returns an API response, but fails to detail critical aspects like whether it's read-only, requires specific permissions, has rate limits, or what happens on errors beyond 'error message'. This leaves significant gaps for a tool interacting with access tokens.
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 the main purpose stated first and a return value note added. Both sentences earn their place by clarifying the action and output, though the return note could be more specific (e.g., format of the list). There's minimal waste, but slight room for improvement in structure.
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 has 0 parameters and no output schema, the description covers the basic purpose and return type adequately. However, it lacks details on behavioral traits (e.g., authentication needs, error handling) and doesn't fully compensate for the absence of annotations, making it minimally viable but incomplete for secure token management.
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 has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately omits parameter details, focusing on the tool's purpose and return value, which aligns with the schema's completeness. A baseline of 4 is applied since no parameters exist and the description doesn't add unnecessary information.
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 ('Retrieve all access tokens') and resource ('for the current Storyblok space using the Management API'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_single_activity' or 'retrieve_multiple_webhooks' beyond the resource type, which prevents a perfect score.
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 'create_access_token' or 'delete_access_token', or any prerequisites like authentication requirements. It lacks explicit when/when-not statements or comparisons to other tools, offering only basic context.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination behavior (defaults and limits for per_page and page) which is valuable, but doesn't describe authentication requirements, rate limits, error conditions, or what the return format looks like (especially critical since there's no output schema). For a read operation with zero annotation coverage, this leaves significant gaps.
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 efficiently structured with a clear opening sentence followed by bullet points for parameters. Every element serves a purpose with minimal waste. It could potentially be more front-loaded with key behavioral information, but overall it's appropriately concise.
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 4 parameters, no annotations, and no output schema, the description provides adequate parameter documentation but lacks critical context about authentication, error handling, and return format. For a retrieval tool with pagination and filtering capabilities, users need to know what structure to expect in response, making this description incomplete despite good parameter coverage.
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 0% schema description coverage, the description must compensate - and it does by explaining all 4 parameters with clear semantics: story_id identifies the target story, per_page controls pagination with defaults/limits, page specifies which page, and by_status enables filtering. This adds substantial value beyond the bare schema, though it doesn't provide examples of status values or deeper context.
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 ('Retrieves multiple discussions') and the target resource ('for a specific story in a Storyblok space'), providing a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from sibling tools like 'retrieve_specific_discussion' or 'retrieve_my_discussions', which would require a 5.
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 like 'retrieve_specific_discussion' (for single discussions) or 'retrieve_my_discussions' (for user-specific discussions). It only documents what the tool does, not when it's appropriate versus other retrieval options.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only operation ('retrieves') but doesn't specify authentication requirements, rate limits, pagination behavior beyond defaults, or error handling. For a tool with no annotation coverage, this leaves significant gaps in understanding its operational characteristics.
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 efficiently structured with a clear purpose statement followed by bullet-point parameter details. Every sentence earns its place, though it could be slightly more front-loaded by emphasizing the user-specific aspect earlier. No wasted verbiage is present.
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 moderate complexity (3 parameters, no output schema, no annotations), the description covers the basic purpose and parameters adequately but lacks behavioral context and usage differentiation. It's minimally viable but has clear gaps in guiding the agent on when and how to use it effectively compared to alternatives.
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 description adds meaningful context for all three parameters: it explains 'space_id' as the 'Numeric ID of the space', provides defaults and limits for 'page' and 'per_page', and clarifies 'by_status' filtering options. With 0% schema description coverage, this compensates well by documenting parameter purposes beyond what the bare 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 the verb ('retrieves') and resource ('discussions you're involved in within a Storyblok space'), making the purpose explicit. However, it doesn't distinguish this from sibling tools like 'retrieve_multiple_discussions' or 'retrieve_specific_discussion', which would require mentioning the user-specific filtering aspect more prominently.
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 like 'retrieve_multiple_discussions' or 'retrieve_specific_discussion'. It mentions the 'space_id' parameter but doesn't explain prerequisites or contextual usage scenarios, leaving the agent with minimal direction.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool creates a branch but doesn't specify whether this requires specific permissions, what happens on success/failure, or any side effects (e.g., if it affects existing branches). This leaves significant gaps for a mutation 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 efficiently structured with a clear opening sentence followed by bullet points for parameters. Every sentence earns its place, and there's no redundant or verbose language. It's appropriately sized for the tool's complexity.
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 no annotations and no output schema, the description adequately covers the basic purpose and parameters but lacks behavioral context (e.g., permissions, effects) and return value information. For a mutation tool with 4 parameters, this is minimally viable but leaves clear 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 0%, so the description must compensate. It provides clear semantic explanations for all 4 parameters (name, source_id, url, position), including which are required/optional and brief purposes. This adds substantial value beyond the bare schema, though it doesn't cover format details like URL validation.
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 ('Creates a new branch') and resource ('in a Storyblok space via the Management API'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'create_space' or 'duplicate_space', which would require a 5.
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 like 'create_space' or 'duplicate_space', nor does it mention any prerequisites or context for usage. It simply states what the tool does without indicating appropriate scenarios.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool fetches details, implying a read-only operation, but doesn't clarify permissions, error handling, rate limits, or what 'details' include. The mention of 'API response' is vague, lacking specifics on format or potential side effects.
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 and concise, with no wasted words. It front-loads the purpose in the first sentence, followed by clear sections for parameters and returns. Each sentence earns its place by providing essential information efficiently.
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 low complexity (single parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and parameter semantics but lacks behavioral details and usage guidelines. Without annotations or output schema, more context on return values or operational constraints would improve completeness.
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 description adds significant value beyond the input schema, which has 0% description coverage. It explicitly defines the single parameter 'folder_id' as 'ID of the asset folder to retrieve,' providing clear semantics. This compensates for the schema's lack of descriptions, making the parameter's purpose understandable.
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's purpose: 'Fetch details of a specific asset folder by its ID.' This specifies the verb ('fetch details'), resource ('asset folder'), and key identifier ('by its ID'). However, it doesn't explicitly differentiate from sibling tools like 'retrieve_asset_folders' (plural) or 'get_asset' (single asset vs folder), which would require a 5.
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 doesn't mention sibling tools like 'retrieve_asset_folders' for listing folders or 'get_asset' for fetching individual assets, nor does it specify prerequisites or contexts for usage. This leaves the agent without explicit direction.
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 are provided, so the description carries full burden. While 'Lists' implies a read-only operation, the description doesn't disclose important behavioral aspects: whether this requires authentication, how results are formatted (e.g., pagination, sorting), if it's always available, or performance characteristics. For a tool with zero annotation coverage, this leaves significant behavioral unknowns.
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, efficient sentence that front-loads the core purpose. Every word earns its place: 'Lists' (action), 'all available tools' (scope), 'with their names, descriptions, and total count' (output details). There's no redundancy or unnecessary elaboration.
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 (zero parameters, no annotations, no output schema), the description is adequate but has clear gaps. It explains what the tool returns at a high level but doesn't provide format details, authentication requirements, or guidance on when to use it versus specific resource queries. For a meta-tool in a large sibling set, more contextual guidance would be helpful.
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 tool has zero parameters (schema description coverage is 100%), so there are no parameters to document. The description appropriately doesn't mention any parameters, which is correct for a parameterless tool. A baseline of 4 is appropriate since the description doesn't need to compensate for any parameter documentation gaps.
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's purpose with a specific verb ('Lists') and resource ('all available tools'), and specifies what information is returned ('names, descriptions, and total count'). However, it doesn't explicitly differentiate this tool from other list/retrieve siblings like 'fetch_spaces' or 'retrieve_multiple_activities' beyond the obvious resource difference.
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. With many sibling tools that retrieve or list resources (e.g., 'fetch_spaces', 'retrieve_multiple_activities'), there's no indication of whether this is a general discovery tool, a meta-tool for exploring capabilities, or when an agent should prefer specific resource queries over this general listing.
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?
With no annotations provided, the description carries full burden. It mentions pagination and search filtering, but doesn't disclose authentication requirements, rate limits, error conditions, or what the return format looks like. For a retrieval tool with 5 parameters, this leaves significant behavioral gaps.
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?
Perfectly structured with a clear purpose statement followed by parameter documentation. Every sentence earns its place - the first establishes what the tool does, the parameter list provides essential usage details without redundancy.
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 retrieval tool with 5 parameters and no annotations or output schema, the description covers parameter semantics well but lacks behavioral context about authentication, response format, or error handling. It's adequate for basic usage but incomplete for robust agent 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?
Schema description coverage is 0%, so the description must compensate. It provides clear explanations for all 5 parameters: context options, meaning of 'only_mine', pagination details, and search functionality. This adds substantial value beyond the bare 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 verb ('Retrieves') and resource ('multiple field plugins'), specifying they are 'field types' across different contexts. It distinguishes from sibling 'retrieve_field_plugin' (singular) by emphasizing 'multiple', but doesn't explicitly contrast with other retrieval tools like 'retrieve_all_extensions'.
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 'retrieve_field_plugin' (singular) or other retrieval tools. The description mentions contexts ('space', 'org', 'partner') but doesn't explain when each is appropriate or provide any exclusion criteria.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the API source ('Management API') but lacks critical details like whether this is a read-only operation, if it requires specific permissions, what the return format looks like, or if there are pagination/rate limits. For a retrieval tool with zero annotation coverage, this is insufficient.
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 efficiently structured with a clear opening sentence followed by bullet points for parameters. Every sentence earns its place, and there's no redundant or verbose language.
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 moderate complexity (2 optional parameters) and lack of annotations/output schema, the description is partially complete. It covers the basic purpose and parameters but misses behavioral aspects like return format, error handling, or usage context. It's adequate but has clear 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?
The description adds meaningful context for both parameters: 'by_ids' is explained as 'Optional comma-separated list of branch IDs to filter' and 'search' as 'Optional filter term for branch names'. This compensates well for the 0% schema description coverage, though it doesn't cover parameter formats or examples exhaustively.
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 ('Retrieves') and resource ('multiple branches (pipelines) in a Storyblok space via the Management API'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_single_branch' or 'fetch_stories', which would be needed for a perfect score.
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 doesn't mention scenarios where this tool is preferred over other retrieval tools in the sibling list, nor does it specify prerequisites or constraints for usage.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a retrieval operation via an API, implying read-only behavior, but doesn't specify authentication requirements, rate limits, error conditions, or what happens if the branch ID doesn't exist. This leaves significant gaps for a tool that interacts with an external API.
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 efficiently structured with a clear main sentence followed by a bullet point for the parameter. There's no wasted text, and information is front-loaded appropriately for quick understanding.
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 no annotations, no output schema, and low schema coverage, the description adequately covers the basic purpose and parameter. However, it lacks details on behavioral aspects like authentication, error handling, or return format, which are important for API-based tools. It's minimally viable but has clear 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 0%, but the description explicitly documents the single parameter 'branch_id' as 'Numeric ID of the branch to retrieve,' which fully compensates for the lack of schema descriptions. This provides clear semantic meaning beyond the schema's type and title.
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 ('Retrieves') and resource ('a single branch (pipeline)'), and specifies it's done via the Storyblok Management API. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_multiple_branches' or 'get_story', though the 'single' vs 'multiple' distinction is implied.
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 'retrieve_multiple_branches' for listing branches or 'get_story' for story data. The description lacks context about prerequisites, such as needing branch ID availability, or when this retrieval is appropriate.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation but doesn't mention whether it's destructive, requires specific permissions, has side effects, or what happens to unspecified fields. It provides minimal behavioral context beyond the basic operation type.
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 well-structured with a clear purpose statement followed by parameter documentation. Each parameter explanation is brief and focused. There's minimal waste, though the formatting with 'Args:' could be slightly more integrated with the main description text.
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 mutation tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It covers parameters well but lacks crucial information about behavioral traits, error conditions, return values, and usage context. The agent would struggle to use this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates fully by providing clear semantic explanations for all 7 parameters. Each parameter gets a brief but meaningful description that adds value beyond the schema's type information, explaining what each field represents and their optional nature.
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 'updates' and the resource 'existing field plugin', specifying it operates 'in the specified context'. It distinguishes from sibling 'create_field_plugin' by focusing on updates rather than creation, though it doesn't explicitly differentiate from other update tools like 'update_extension'.
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 doesn't mention prerequisites like authentication, permissions, or when to choose this over other update tools. The only implied usage is for modifying field plugins, but no explicit context or exclusions 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'adds a collaborator' but does not clarify if this is a mutating operation, what permissions are needed, how errors are handled, or what the output looks like. It lacks essential context for safe and effective use.
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 the purpose, followed by parameter guidance. Both sentences are necessary, with no redundant information, though it could be slightly more structured for clarity.
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 the complexity of a mutation tool with 6 parameters, 0% schema coverage, no annotations, and no output schema, the description is insufficient. It covers parameter usage but omits behavioral traits, error handling, and output details, leaving critical gaps for agent 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?
The description adds significant value by explaining the exclusive usage of 'role', 'space_role_id', or 'space_role_ids', which clarifies parameter relationships not evident in the schema (0% coverage). However, it does not explain other parameters like 'allow_multiple_roles_creation' or 'permissions', leaving some gaps.
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 'adds' and the resource 'collaborator to a space in Storyblok', specifying the exact action and target. It distinguishes from siblings like 'delete_collaborator' and 'update_collaborator' by focusing on creation rather than removal or modification.
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 'create_space_role' or 'update_collaborator', nor does it mention prerequisites like required permissions or existing space context. It only includes parameter usage rules, not tool selection advice.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it 'creates' something, implying a write operation, but doesn't mention permissions required, whether it's idempotent, what happens on failure, or the response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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?
The description is appropriately sized with two sentences: one stating the tool's purpose and another detailing parameters. It's front-loaded with the main action and avoids unnecessary fluff, though the parameter explanations could be slightly more integrated into the flow for perfect structure.
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 complexity (a write operation with 2 parameters), no annotations, and no output schema, the description is minimally adequate. It covers the purpose and parameters well but lacks behavioral details like error handling or response format, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the input schema, which has 0% description coverage. It explains that 'story_id' is the 'Numeric ID of the content entry to be approved' and 'approver_id' is the 'Numeric ID of the user who will approve it', clarifying the purpose and format of both parameters. This fully compensates for the schema's lack of descriptions.
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 ('creates an approval request') and the target resource ('for a story (and optional release) in a Storyblok space'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'create_release_approval' or 'retrieve_multiple_approvals', which would be needed for a perfect score.
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 like 'create_release_approval' or how it relates to other approval-related tools. It mentions an 'optional release' but doesn't clarify when that parameter applies or if there are prerequisites, leaving usage context implied at best.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that 'compiled_body' is 'Required; empty string if developing locally', which hints at development workflows, but lacks critical details like permissions needed, whether the creation is irreversible, rate limits, or what happens on success/failure. For a creation tool with zero annotation coverage, this is insufficient.
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 appropriately sized and front-loaded, starting with the main purpose. The parameter explanations are concise and informative, though the formatting with 'Args:' could be slightly more integrated. Every sentence adds value without redundancy.
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 complexity (creation operation with 4 parameters), no annotations, and no output schema, the description is partially complete. It covers parameter semantics well but lacks behavioral context like error handling, return values, or system constraints. It's adequate as a baseline but has clear gaps for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains each parameter's purpose: 'name' as a unique identifier with an example, 'body' as JavaScript source, 'compiled_body' as required with a development note, and 'context' with allowed values. This fully compensates for the schema's lack of descriptions.
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 ('Creates') and resource ('a new field plugin (field type)'), making the purpose evident. However, it doesn't differentiate from sibling tools like 'create_extension' or 'create_component', which might create similar types of resources in the same system.
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 like 'create_extension' or 'update_field_plugin', nor does it mention prerequisites or typical use cases. It only states the context parameter options without explaining their implications.
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 are provided, so the description carries full burden. It states the tool retrieves data, implying read-only behavior, but does not disclose critical traits like authentication requirements, rate limits, pagination, error handling, or what 'all extensions' entails (e.g., format, completeness). For a retrieval tool with zero annotation coverage, this leaves significant behavioral gaps.
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 appropriately sized with two sentences: one stating the purpose and another explaining the parameter. It is front-loaded with the main action and avoids redundancy. However, the formatting with extra whitespace slightly detracts from structure, but overall it is efficient and clear.
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 low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and parameter semantics but lacks details on behavioral aspects like return format, errors, or system limits. Without annotations or output schema, more context on what 'retrieves' entails would improve completeness for agent use.
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 description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains the 'context' parameter with specific options ('org' or 'partner'), clarifying its purpose and valid values. Since there is only one parameter and the schema lacks descriptions, the description effectively compensates, though it could detail default behaviors or constraints.
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 ('Retrieves all extensions') and resource ('extensions (plugins)'), with specificity about scope ('from the specified context'). It distinguishes from some siblings like 'retrieve_extension' (singular) but not from 'retrieve_field_plugins' which might overlap in function. Purpose is clear but sibling differentiation could be more explicit.
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 by specifying the context parameter options ('org' or 'partner'), suggesting when to use based on context level. However, it does not explicitly state when to choose this tool over alternatives like 'retrieve_extension' or 'retrieve_field_plugins', nor does it mention prerequisites or exclusions. Usage is implied but not fully guided.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data (implying read-only) but doesn't mention authentication requirements, rate limits, pagination behavior, error handling, or what 'multiple presets' entails (e.g., all presets vs. a subset). For a retrieval tool with zero annotation coverage, this leaves significant gaps.
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 just two sentences that directly address the tool's purpose and parameter usage. Every word earns its place, and it's front-loaded with the core functionality. No wasted verbiage or redundancy.
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 no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., format of presets, error responses), authentication needs, or behavioral constraints. For a tool interacting with an API, this leaves too many unknowns for effective agent use.
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 description adds meaningful context for the single parameter by explaining that component_id is used for optional filtering. Since schema description coverage is 0% (the schema only provides a title 'Component Id'), the description compensates well by clarifying the parameter's purpose, though it doesn't specify format details like what integer values are valid.
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 ('Retrieves multiple presets') and resource ('from a Storyblok space using the Management API'), which is specific and informative. However, it doesn't explicitly differentiate from sibling tools like 'retrieve_single_preset' or 'fetch_components', which would be needed for a perfect score.
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 mentions optional filtering by component_id, which implies when to use this parameter, but doesn't provide explicit guidance on when to choose this tool over alternatives like 'retrieve_single_preset' or other retrieval tools in the sibling list. Usage context is implied rather than clearly stated.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's an update operation, implying mutation, but lacks details on permissions required, whether changes are reversible, rate limits, or error handling. The mention of 'Management API' hints at administrative access but is not explicit. For a mutation tool with zero annotation coverage, this is insufficient.
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 well-structured with clear sections (Params, Request Body, Returns) and uses bullet points for readability. It is appropriately sized, though the 'Returns' section could be more specific instead of 'Any: A success message or an error message', which is somewhat vague.
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 complexity (6 parameters, mutation operation) and lack of annotations and output schema, the description is moderately complete. It covers parameters well but misses behavioral context (e.g., side effects, auth needs) and return value details. For a tool with no structured safety or output info, it should provide more guidance on usage and outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the input schema, which has 0% description coverage. It clearly explains each parameter's purpose (e.g., 'New access level for the token', 'New name for the token'), including optional ones and their semantics, compensating fully for the schema's lack of descriptions.
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 an existing access token') and resource ('in the current Storyblok space via the Management API'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'create_access_token' or 'delete_access_token', which would require mentioning what distinguishes an update from creation or deletion.
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 mention prerequisites (e.g., needing an existing token ID), compare it to 'create_access_token' or 'delete_access_token', or specify scenarios where updating is appropriate (e.g., modifying permissions or renewing tokens).
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?
With no annotations provided, the description carries full burden. It states it's an update operation (implying mutation) and mentions the current Storyblok space context, but lacks critical behavioral details: permission requirements, whether changes are reversible, error handling, rate limits, or what 'success message or error content' entails. The request body example helps but doesn't fully compensate.
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 (purpose, parameters, example, returns). Every sentence earns its place, but the returns statement is vague ('success message or error content') and could be more precise. Slightly front-loaded with the core purpose first.
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 3 parameters, no annotations, and no output schema, the description is moderately complete. It covers parameters well and provides an example, but lacks behavioral context (permissions, side effects) and output details. For a mutation tool with zero annotation coverage, it should do more to explain risks and responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It explicitly lists all three parameters with types and semantics: folder_id as required ID, name as optional new name, and parent_id as optional new parent folder ID. The request body example further clarifies structure and usage, adding significant value beyond the bare 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'), resource ('existing asset folder'), and scope ('in the current Storyblok space'), with specific attributes ('name or parent'). It distinguishes from create_asset_folder by specifying 'existing', but doesn't explicitly differentiate from other update tools like update_asset or update_component_folder.
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 doesn't mention prerequisites (e.g., needing folder_id), when not to use it, or compare with sibling tools like update_asset or update_component_folder. The context is implied but not explicit.
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?
With no annotations, the description carries full burden but only states it's an update operation via the Management API. It lacks details on permissions required, whether changes are reversible, rate limits, or what happens to unspecified fields, which are critical for a mutation tool.
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 front-loaded with the core purpose, followed by a bulleted list of parameters. It's efficient with minimal waste, though the bullet formatting could be slightly more structured for readability.
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 mutation tool with 5 parameters, no annotations, and no output schema, the description covers parameters well but lacks behavioral context and output details. It's partially complete but leaves gaps in understanding the tool's full impact and response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by clearly explaining all 5 parameters: branch_id as required numeric ID, and optional fields (name, source_id, url, position) with brief semantics. This adds significant value beyond the bare 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 ('Updates') and resource ('an existing branch (pipeline) in a Storyblok space'), specifying it uses the Management API. It distinguishes from siblings like 'create_branch' by focusing on updates, but doesn't explicitly contrast with other update tools like 'update_space' or 'update_story'.
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. It doesn't mention prerequisites, such as needing a branch_id, or compare with other update tools in the sibling list, leaving the agent to infer usage context.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool performs a deletion but doesn't mention critical details like whether this action is irreversible, what happens to assets inside the folder, permission requirements, or error conditions. For a destructive operation, this is a significant gap in 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 appropriately sized with three focused sentences: purpose statement, parameter documentation, and return value note. It's front-loaded with the core action and wastes no words, though the return value description could be more precise.
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 destructive tool with no annotations and no output schema, the description provides basic purpose and parameter information but lacks crucial behavioral context about deletion consequences, permissions, and error handling. It's minimally adequate but has clear gaps given the tool's complexity and risk profile.
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 0%, but the description explicitly documents the single parameter 'folder_id' with its type and purpose, fully compensating for the schema gap. It adds essential meaning beyond the bare schema, though it doesn't specify format constraints 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 the specific action ('Delete') and resource ('an asset folder from the current Storyblok space'), distinguishing it from siblings like 'delete_asset' or 'delete_component_folder' by specifying the exact resource type. It provides a complete verb+resource+scope statement.
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 like 'delete_multiple_assets' or 'bulk_delete_stories', nor does it mention prerequisites such as needing folder permissions or checking if the folder is empty. It lacks explicit when/when-not instructions or named alternatives.
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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool creates a token via the Management API but doesn't specify required permissions, whether this is a write operation (implied but not stated), rate limits, error conditions, or what happens to existing tokens. The return value description ('API response containing the created access token or an error message') is minimal and doesn't explain format or structure.
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 well-structured with clear sections for the main purpose, request body parameters, and return value. Each sentence adds value, though the return value description could be more specific. The formatting with bullet-like parameter explanations is efficient and easy to parse.
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 complexity (5 parameters, mutation operation) and lack of both annotations and output schema, the description is partially complete. It excels at parameter documentation but lacks behavioral context about permissions, side effects, and detailed return format. For a creation tool with no structured safety information, more behavioral disclosure would be needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides comprehensive parameter documentation beyond the schema, which has 0% description coverage. It clearly explains all 5 parameters with their purposes, data types, and optionality (e.g., 'access (str): The access level for the token (e.g., 'draft', 'published')', 'story_ids (Optional[List[int]]): Optional list of story IDs to restrict access'). This fully compensates for the schema's lack of 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 specific action ('Create a new access token') and resource ('in the current Storyblok space via the Management API'), distinguishing it from sibling tools like 'delete_access_token' and 'update_access_token'. It uses precise terminology that leaves no ambiguity about what the tool does.
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 like 'retrieve_multiple_access_tokens' or 'update_access_token'. It mentions the context ('current Storyblok space') but doesn't specify prerequisites, constraints, or typical use cases for creating access tokens versus other token-related operations.
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 are provided, so the description carries the full burden. It discloses that the operation is a deletion (destructive) and includes a constraint about the default workflow, adding useful behavioral context. However, it lacks details on permissions, error handling, or confirmation steps, which are important for a destructive tool, leaving gaps in transparency.
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, front-loaded with the core action and resource, followed by a key constraint. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.
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 complexity (destructive operation with no annotations and no output schema), the description is moderately complete. It covers the basic action and a constraint, but lacks details on permissions, response format, or error cases, which are crucial for safe invocation. It meets minimum viability but has clear gaps.
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 0% description coverage, with one parameter 'workflow_id' of type integer. The description adds minimal semantics by implying 'workflow_id' is used to identify the workflow to delete, but it does not explain format, valid ranges, or where to obtain the ID. This partially compensates for the low schema coverage but is insufficient for full clarity.
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 ('Deletes') and resource ('a workflow by its ID in a Storyblok space via the Management API'), making the purpose explicit. However, it does not differentiate from sibling tools like 'delete_workflow_stage' or 'delete_space', which also delete resources, so it lacks sibling distinction for a perfect score.
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 some context with 'The default workflow cannot be deleted,' which implies a usage constraint, but it does not explicitly state when to use this tool versus alternatives (e.g., 'delete_workflow_stage' or general deletion tools) or mention prerequisites like permissions. This gives implied guidance but falls short of explicit alternatives.
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 annotations provided, the description carries the full burden. It correctly identifies this as a creation operation (implying mutation) and mentions the Storyblok space context, but lacks details on permissions, rate limits, error handling, or whether the operation is idempotent. It provides basic behavioral context but misses important operational details for a mutation tool.
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 well-structured with clear sections (purpose, parameters, example, returns) and uses minimal sentences. The request body example is helpful but slightly verbose; overall it's efficient with good information density.
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 mutation tool with no annotations and no output schema, the description provides adequate basic information (purpose, parameters, example) but lacks important context about permissions, error responses, space requirements, or how the created folder integrates with other operations. It's minimally viable but has clear gaps for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by clearly explaining both parameters: 'name' as the folder name and 'parent_id' as optional nesting with an example. It adds significant value beyond the bare schema, providing practical usage context and formatting 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 clearly states the specific action ('Create a new asset folder') and resource ('in the current Storyblok space'), distinguishing it from sibling tools like 'create_component_folder' or 'create_space' by specifying the asset folder context. It provides a complete verb+resource+scope statement.
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 like 'update_asset_folder' or 'retrieve_asset_folders', nor does it mention prerequisites such as required permissions or space context. It lacks explicit when/when-not instructions or sibling comparisons.
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?
With no annotations provided, the description carries full burden but only states the deletion action without disclosing behavioral traits. It doesn't mention required permissions, whether the deletion is reversible, what happens to associated data, or any rate limits. For a destructive operation, this is a significant gap in transparency.
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 perfectly concise with two sentences that each earn their place: the first states the core purpose, the second explains parameter usage. There's zero waste and it's appropriately front-loaded with the main action.
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 destructive tool with no annotations and no output schema, the description provides adequate basic information about what it does and parameter usage, but lacks crucial context about permissions, consequences, and response format. It's minimally viable but has clear gaps given the tool's complexity and potential impact.
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 description adds meaningful semantics beyond the schema by explaining that you can delete 'by numeric collaborator_id or by sso_id for SSO users', clarifying the purpose and relationship between the two parameters. With 0% schema description coverage, this effectively compensates for the schema's lack of parameter documentation.
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 specific action ('Deletes') and target ('a collaborator from a specified Storyblok space'), distinguishing it from sibling tools like 'add_collaborator' and 'update_collaborator'. It precisely defines what the tool does without being tautological.
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 by mentioning two alternative identifiers (collaborator_id or sso_id), but doesn't explicitly state when to use this tool versus alternatives like 'update_collaborator' or 'retrieve_multiple_collaborators'. It provides some context but lacks explicit guidance on prerequisites or exclusions.
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?
With no annotations provided, the description carries full burden but only states what it checks without disclosing behavioral traits like response format, error conditions, authentication requirements, or rate limits. It's a read-only diagnostic tool, but these operational details are missing.
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, efficient sentence with zero waste—every word contributes to understanding the tool's purpose. It's appropriately sized and front-loaded with the core functionality.
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 zero-parameter diagnostic tool with no annotations and no output schema, the description is minimally adequate but lacks completeness regarding what the check returns (e.g., status details, latency metrics) or how failures are indicated. It covers the 'what' but not the 'how' of the 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?
The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, maintaining focus on the tool's purpose without unnecessary 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's purpose with specific verbs ('checks server health and Storyblok API connectivity'), distinguishing it from all sibling tools which perform CRUD operations on Storyblok resources. It precisely identifies what it does without restating the name.
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 health/connectivity checking, but doesn't explicitly state when to use it versus alternatives (e.g., for troubleshooting vs. operational monitoring) or provide any exclusions. Usage context is inferred rather than explicitly guided.
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 are provided, so the description carries the full burden. It indicates this is a read operation ('Retrieve'), but lacks details on permissions, rate limits, pagination, or error handling. The mention of 'API response' hints at external behavior, but remains vague. It adds minimal behavioral context beyond the basic action.
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 and front-loaded with the core purpose, followed by a clear parameter list and return statement. Every sentence adds value without redundancy, and it avoids unnecessary elaboration, making it efficient for quick understanding.
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 moderate complexity (4 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose and parameters adequately but lacks behavioral details like error handling, pagination, or usage context, leaving gaps for an AI agent to infer.
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 0% schema description coverage, the description compensates by listing all four parameters with brief explanations of their purposes (e.g., 'filter asset folders by name', 'ID of the parent folder to filter results'). This adds meaningful semantics beyond the schema's titles, though it lacks format examples 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 the specific action ('Retrieve a list of asset folders') and resource ('from the current Storyblok space'), distinguishing it from siblings like 'fetch_asset_folder' (singular) and 'fetch_assets' (different resource). It precisely communicates the tool's function without redundancy.
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 mention sibling tools like 'fetch_asset_folder' (for single folders) or 'fetch_assets' (for assets rather than folders), nor does it specify prerequisites, exclusions, or contextual usage scenarios.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a retrieval operation, implying read-only behavior, but doesn't mention permissions required, rate limits, error conditions, or what the return format looks like. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
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 perfectly concise: one sentence stating the purpose, followed by a structured Args section explaining parameters. Every sentence earns its place with no wasted words, and the information is front-loaded appropriately.
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 retrieval tool with 2 parameters, the description covers the basic purpose and parameters well. However, with no annotations and no output schema, it should ideally mention what gets returned (extension settings) and any behavioral constraints. It's adequate but has clear gaps given the lack of structured metadata.
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 0%, so the description must compensate. It provides clear semantic meaning for both parameters: extension_id is 'the numeric ID of the extension' and context specifies 'org for organization-level or partner for partner-level extensions'. This adds substantial value beyond the bare 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 ('retrieves') and resource ('settings of a specific extension'), and distinguishes it from sibling tools like 'retrieve_all_extensions' by specifying retrieval by numeric ID rather than all extensions. It's 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning the need for an extension ID and context, but doesn't explicitly state when to use this tool versus alternatives like 'retrieve_all_extensions' or 'retrieve_extension_settings'. No exclusions or prerequisites are provided.
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:

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

Score Badge

Copy to your README.md:

[![storyblok-mcp-server MCP server](https://glama.ai/mcp/servers/Kiran1689/storyblok-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/Kiran1689/storyblok-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/Kiran1689/storyblok-mcp-server'

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