Thinkific MCP Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation3/5
Most tools have distinct purposes, but there is significant overlap between REST and GraphQL versions (e.g., get_category vs gql_category, list_courses vs gql_course queries). This duplication can cause confusion for agents trying to select the appropriate tool, though descriptions clarify the API differences.
Naming Consistency4/5
Tools follow consistent verb_noun patterns within each API style (REST and GraphQL), with clear conventions like create_, get_, list_, update_, delete_. The 'gql_' prefix distinguishes GraphQL tools, maintaining readability despite the dual API approach.
Tool Count2/5
With 109 tools, the count is excessive for a single server, overwhelming typical agent workflows. While Thinkific's domain is broad, this many tools indicates poor scoping, likely due to redundant API implementations rather than necessary functional coverage.
Completeness4/5
The tool set provides comprehensive CRUD and lifecycle coverage across users, courses, products, promotions, and community features, with both REST and GraphQL APIs. Minor gaps might exist in niche areas, but core operations are well-covered for the e-learning platform domain.
Average 2.9/5 across 100 of 109 tools scored.
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.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
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

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. 'Refund' implies a financial mutation, but the description doesn't state whether this requires specific permissions, if it's reversible, what happens to the order status, or any rate limits or side effects. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Refund an external order.' It's front-loaded with the core action and resource, with no wasted words. However, it could be more structured by including brief usage notes, but as-is, it's concise and to the point.
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 financial mutation with 2 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral nuances like partial vs. full refunds. For a refund operation, more context is needed to ensure safe and correct usage by 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?
The input schema has 100% description coverage, with clear parameter documentation: 'order_id' as the external order ID to refund and 'amount_cents' as the optional refund amount in cents. The description adds no additional semantic context beyond what the schema provides, such as examples or edge cases. With high schema coverage, the baseline score of 3 is appropriate.
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 'Refund an external order' clearly states the action (refund) and target resource (external order), which is adequate. However, it doesn't differentiate from potential siblings like 'purchase_external_order' or 'get_order', nor does it specify what makes an order 'external' versus internal. The purpose is understandable but lacks specificity about scope or 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. It doesn't mention prerequisites (e.g., order must exist, be refundable), exclusions (e.g., cannot refund already refunded orders), or related tools like 'purchase_external_order' or 'get_order' for verification. Without such context, an agent might misuse it or overlook necessary checks.
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. 'Create' implies a write/mutation operation, but the description doesn't disclose any behavioral traits: no information about permissions needed, whether it's idempotent, what happens on duplicate reviews, error conditions, or what the tool returns. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just three words: 'Create a course review.' It's front-loaded with the core action and resource, with zero wasted words or unnecessary elaboration. This is appropriately sized for what it communicates.
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, no annotations, and no output schema, the description is incomplete. It doesn't explain what happens after creation, what the tool returns, error handling, or behavioral constraints. The 100% schema coverage helps with parameters, but overall context for proper tool use is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters with their types, constraints, and basic descriptions. The description adds no additional parameter information beyond what's in the schema. According to the rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 'Create a course review' clearly states the action (create) and resource (course review), which is better than a tautology. However, it doesn't differentiate from sibling tools like 'create_user' or 'create_category' beyond the resource type, and it lacks specificity about what a 'course review' entails beyond the basic verb+noun.
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., user must be enrolled), when not to use it, or how it relates to sibling tools like 'get_course_review' or 'list_course_reviews'. It's a bare 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?
No annotations are provided, so the description carries full burden. 'Delete a coupon' implies a destructive mutation, but it doesn't disclose behavioral traits such as whether deletion is permanent, requires specific permissions, has side effects (e.g., affecting related orders), or what the response looks like. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, 'Delete a coupon.', which is front-loaded and wastes no words. Every part of the sentence directly contributes to the purpose, making it efficient in 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 (a destructive mutation with no annotations and no output schema), the description is incomplete. It lacks crucial context like behavioral details, usage guidelines, and output expectations. For a delete operation, this minimal description leaves too many gaps for 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 100%, with the parameter 'coupon_id' documented as 'The coupon ID to delete'. The description adds no additional meaning beyond this, such as format examples or where to find the ID. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
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 'Delete a coupon' clearly states the action (delete) and resource (coupon), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'delete_category' or 'delete_user' beyond the resource name, and it lacks specificity about what 'delete' entails in this 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. It doesn't mention prerequisites (e.g., needing the coupon ID), when deletion is appropriate, or what happens after deletion. With sibling tools like 'get_coupon' and 'update_coupon', there's no indication of how this fits into a workflow.
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 'Delete a promotion' which implies a destructive mutation, but doesn't specify whether this is permanent, reversible, requires specific permissions, has side effects (e.g., affecting associated coupons or orders), or what happens on success/failure. For a destructive operation 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 maximally concise with a single clear sentence: 'Delete a promotion.' There's zero wasted language or redundancy. It's appropriately sized for a simple operation and front-loads 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 this is a destructive mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address critical context like what happens after deletion, whether there are confirmation steps, error conditions, or system impacts. The single sentence leaves too many behavioral questions unanswered for a tool that permanently removes data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the single parameter 'promotion_id' well-documented in the schema. The description adds no additional parameter information beyond what the schema provides. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 'Delete a promotion' clearly states the action (delete) and resource (promotion), but it's vague about scope and doesn't differentiate from sibling tools like delete_category or delete_coupon. It provides basic purpose but lacks specificity about what constitutes a promotion in this 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 about when to use this tool versus alternatives. There's no mention of prerequisites (e.g., whether the promotion must exist or be inactive), no warnings about irreversible deletion, and no comparison to related tools like update_promotion or get_promotion. The description offers zero 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 full burden. It states it 'returns' data, implying a read-only operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or what happens if the ID is invalid. The mention of GraphQL adds some context but is insufficient for full 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 core purpose and includes the GraphQL context concisely, 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 (one parameter, read-only), no annotations, and no output schema, the description is incomplete. It lacks details on return values, error cases, or how it differs from similar tools, leaving gaps for an AI agent to understand full usage 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 100% description coverage, with the 'id' parameter documented as 'The category ID'. The description adds no additional meaning beyond this, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
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 'Returns a Category by ID (GraphQL)' clearly states the action (returns) and resource (Category), but it's vague about what 'Category' entails and doesn't distinguish from sibling tools like 'get_category' or 'list_categories'. It specifies GraphQL as the method but lacks detail on scope or content.
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_category' or 'list_categories'. The description implies it's for fetching a single category by ID but doesn't mention prerequisites, exclusions, or comparative contexts with other 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 full burden but only states the action without behavioral details. It doesn't disclose permissions needed, side effects (e.g., whether unpinning affects post visibility or ordering), error conditions, or response format. 'Unpin' implies a mutation, but this isn't explicitly confirmed.
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 no wasted words—a single sentence that directly states the tool's purpose. It's front-loaded and appropriately sized for a simple operation.
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 and no output schema, the description is incomplete for a mutation tool. It lacks details on behavior, return values, error handling, or dependencies, leaving significant gaps for the agent to operate 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 100%, with the parameter 'postId' well-documented in the schema. The description adds no additional parameter semantics beyond implying 'postId' is required for the unpin action, meeting the baseline for high 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 'Unpin a post (GraphQL)' clearly states the action (unpin) and resource (post), but it's vague about what 'unpin' means operationally and doesn't differentiate from sibling tools like 'gql_pin_post' beyond the obvious opposite action. It specifies GraphQL implementation, which adds some 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 or prerequisites. While 'gql_pin_post' is a clear sibling, the description doesn't explicitly reference it or explain usage context, leaving the agent to infer 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 the full burden of behavioral disclosure. It states 'List' which implies a read-only operation, but doesn't cover aspects like pagination behavior (implied by parameters but not described), rate limits, authentication needs, or what the output looks like (no output schema). This is a significant gap for a tool with parameters and no structured safety hints.
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—'List product publish requests' is front-loaded and directly conveys the core action. It's appropriately sized for a simple list operation, earning full marks 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 has parameters (page, limit) and no output schema, the description is incomplete. It doesn't explain the paginated nature of the listing, what fields are returned, or how results are structured. For a list tool with pagination, this lack of contextual detail makes it inadequate for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear documentation for 'page' and 'limit' parameters including defaults and constraints. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 for adequate coverage without extra value.
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 'List product publish requests' clearly states the verb ('list') and resource ('product publish requests'), making the purpose understandable. However, it doesn't distinguish this tool from similar list tools like 'list_products' or 'get_publish_request' among the siblings, leaving room for ambiguity about its specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 'get_publish_request' (likely for a single request) and 'list_products' (for products themselves), there's no indication of context, prerequisites, or exclusions, leaving the agent to infer usage based on 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 full burden for behavioral disclosure. 'Update' implies a mutation operation, but the description doesn't specify required permissions, whether changes are reversible, error conditions (e.g., invalid category_id), or what happens to unspecified fields. It lacks critical context 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 zero wasted words. It's appropriately sized for a simple update operation and front-loads the essential 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?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what 'update' entails behaviorally, what permissions are needed, what the response contains, or how it differs from related operations. The 100% schema coverage helps, but the description should provide more context for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter documentation in the schema itself. The description adds no additional parameter information beyond what's in the schema (category_id, name, description). Baseline score of 3 is appropriate since the schema does the heavy lifting.
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 'Update an existing category' clearly states the verb ('update') and resource ('category'), but it's vague about what specifically gets updated. It doesn't differentiate from sibling tools like 'update_user' or 'update_promotion' beyond the resource name, nor does it specify which aspects of a category can be modified.
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 category ID), contrast with 'create_category' for new categories, or indicate when other tools like 'add_products_to_category' might be more appropriate for related 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 but only states it's an update operation. It doesn't disclose behavioral traits such as required permissions, whether updates are reversible, rate limits, or what happens to unspecified fields (e.g., partial vs. full updates). 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 zero waste. It's front-loaded and appropriately sized for the tool's purpose, though it could benefit from more detail given the lack of 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like error handling, response format, or side effects, and relies solely on the input schema, which is 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters (coupon_id, code, note, quantity, expires_at). The description adds no additional meaning beyond implying updates involve these fields, meeting the baseline for high schema coverage without extra value.
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 'Update an existing coupon' clearly states the verb (update) and resource (coupon), but it's vague about what aspects can be updated. It doesn't differentiate from sibling tools like 'update_promotion' or 'update_category' beyond the resource name, and doesn't specify the scope of updates (e.g., code, quantity, expiry).
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., coupon must exist), when not to use it (e.g., for creation vs. update), or refer to sibling tools like 'create_coupon' or 'delete_coupon' 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Update an existing promotion' implies a mutation operation but doesn't disclose any behavioral traits: it doesn't mention permissions required, whether partial updates are allowed, if changes are reversible, rate limits, or what happens to unspecified fields. 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 waste. It's appropriately sized and front-loaded, stating the core purpose immediately 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 mutation tool with 8 parameters, no annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, partial updates, or response format. Given the complexity and lack of structured data, it should provide more context about how the tool behaves and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters with clear descriptions. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't explain relationships between parameters like discount_type and amount). Baseline 3 is appropriate when the schema does the heavy lifting.
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 'Update an existing promotion' clearly states the verb (update) and resource (promotion), but it's vague about what aspects can be updated. It doesn't distinguish from sibling tools like 'update_coupon' or 'update_category' beyond the resource name, nor does it specify the scope of updates possible.
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 promotion ID), when not to use it, or how it differs from similar update tools like 'update_coupon' or 'update_category' 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 full burden but only states the action without behavioral details. It doesn't disclose required permissions, whether this is a mutation (implied by 'Add'), potential side effects, error conditions, or response format, which are critical for a tool that likely modifies group access.
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 directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, 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 mutation tool with no annotations and no output schema, the description is insufficient. It lacks details on behavioral traits, error handling, or return values, leaving significant gaps for an AI agent to operate effectively 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?
Schema description coverage is 100%, with both parameters ('group_id' and 'user_id') clearly documented in the schema. The description adds no additional semantic context beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high 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 ('Add a user') and the role ('as an analyst (manager) for a group'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'add_user_to_group' or 'remove_group_analyst', which would require mentioning distinctions in permissions or roles.
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., user/group existence), when not to use it, or how it differs from similar tools like 'add_user_to_group' or 'gql_bulk_add_users_to_groups', leaving the agent to infer 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 the full burden of behavioral disclosure. While 'Add' implies a write/mutation operation, it doesn't specify whether this requires specific permissions, whether it's idempotent (e.g., what happens if products are already in the category), or what the response looks like. The description lacks crucial behavioral 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 a single, efficient sentence that gets straight to the point with no wasted words. The parenthetical 'collection membership' adds useful context without being verbose. However, it could be slightly more structured by explicitly mentioning the 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?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens on success/failure, whether there are side effects (e.g., affecting product listings), or any rate limits/constraints. The context signals show this is a write operation that needs more behavioral disclosure than provided.
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 100%, with both parameters ('category_id' and 'product_ids') clearly documented in the schema. The description doesn't add any additional parameter semantics beyond what's already in the schema (e.g., format details, constraints, or examples), so it meets the baseline for high 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 ('Add products to a category') and specifies the resource ('category') and target ('products'), with the parenthetical 'collection membership' providing additional context about the relationship. However, it doesn't explicitly differentiate from its sibling 'remove_products_from_category' beyond the verb difference, which is why it doesn't reach 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_category' or 'list_category_products', nor does it mention prerequisites such as needing existing categories and products. There's no explicit 'when' or 'when-not' context 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 full burden for behavioral disclosure. 'Add a user to a group' implies a mutation operation, but it doesn't specify required permissions, whether the operation is idempotent, error conditions (e.g., invalid IDs), or what happens on success. 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 that gets straight to the point with zero wasted words. It's appropriately sized for a simple tool with two parameters and follows a clear subject-verb-object structure. 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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, idempotency, or error handling. While the schema covers parameters well, the overall context for safe and effective tool invocation is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly documented in the schema ('group_id' and 'user_id' with type and constraints). The description adds no additional parameter information beyond what's in the schema. According to guidelines, when schema coverage is high (>80%), the baseline score is 3 even with no param info in the 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 ('Add') and resources ('user', 'group'), making the purpose immediately understandable. It distinguishes from sibling tools like 'create_user' or 'create_group' by focusing on membership rather than creation. However, it doesn't explicitly differentiate from similar tools like 'gql_bulk_add_users_to_groups' which handles 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., user and group must exist), when to choose bulk operations ('gql_bulk_add_users_to_groups'), or what happens if the user is already in the group. 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. 'Approve' implies a mutation that changes request state, but the description doesn't specify permissions required, whether approval is reversible, what side effects occur (e.g., product publication), or error conditions. 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, focused sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and efficient for an agent 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?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'approve' entails operationally, what happens to the product or request afterward, possible return values, or error handling. The agent lacks critical 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, with the single parameter 'request_id' clearly documented in the schema. The description adds no additional parameter information beyond what's already in the structured data, meeting the baseline for high 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 ('Approve') and resource ('a product publish request'), making the purpose immediately understandable. It doesn't differentiate from its sibling 'deny_publish_request' beyond the opposite action, but the verb+resource combination is specific enough 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 'deny_publish_request' or 'get_publish_request'. There's no mention of prerequisites, valid states for the request, or what happens after approval. 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 'bulk-create' which implies a write operation, but fails to specify permissions required, whether it's idempotent, error handling for duplicate codes, rate limits, or what happens if the promotion doesn't exist. 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 that states the core purpose without unnecessary words. It's appropriately sized and front-loaded with the essential information, making it easy for an agent 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 bulk creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, how errors are handled, or important behavioral aspects like whether all codes must be unique. Given the complexity of bulk operations and lack of structured metadata, 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?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, maintaining the baseline score of 3 where the schema does the heavy lifting.
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 ('bulk-create multiple coupon codes') and resource ('under a promotion'), which is specific and informative. However, it doesn't explicitly distinguish this tool from its sibling 'create_coupon', which appears to create single coupons, 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 like 'create_coupon' or other coupon-related tools. It lacks context about prerequisites, constraints, or typical scenarios for bulk creation, 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 the full burden of behavioral disclosure. It states the action ('Enroll') which implies a write/mutation operation, but doesn't disclose any behavioral traits such as permissions required, whether it's idempotent, what happens on duplicate enrollment, error conditions, or response format. 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 that states the core purpose without any wasted words. It's appropriately sized and front-loaded with the essential information. 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after enrollment (e.g., success response, error handling), behavioral implications, or system effects. Given the complexity of user-bundle relationships and the lack of structured metadata, the description should provide more contextual information about the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters with their types and basic descriptions. The description adds no additional parameter semantics beyond what's in the schema (no format examples, constraints, or relational context). This meets the baseline of 3 when the schema does the heavy lifting.
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 ('Enroll') and target ('a user in a bundle'), providing a specific verb+resource combination. It distinguishes from siblings like 'create_enrollment' (which might be more general) and 'update_bundle_enrollment' (which modifies existing enrollments). However, it doesn't explicitly differentiate from 'gql_bundle' or other bundle-related tools, keeping it at a 4 rather than 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. There's no mention of prerequisites (e.g., user and bundle must exist), when not to use it (e.g., for existing enrollments), or explicit alternatives like 'update_bundle_enrollment' for modifications. 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?
No annotations are provided, so the description carries full burden. It states the tool creates a new category, implying a write/mutation operation, but doesn't disclose behavioral traits such as required permissions, whether the operation is idempotent, what happens on duplicate names, or the response format. 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 that front-loads the purpose ('Create a new category') and adds clarifying context ('collection for organizing products'). There is zero waste, and 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 as a mutation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., permissions, idempotency), response format, or error handling. For a create operation in a system with many sibling tools, 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 100%, with clear descriptions for 'name' and 'description' parameters. The description adds no additional parameter semantics beyond what the schema provides (e.g., it doesn't explain naming conventions or description usage). Baseline is 3 since the schema does the heavy lifting, but the description doesn't compensate with extra insights.
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 ('Create') and resource ('new category/collection'), specifying it's for organizing products. It distinguishes from siblings like 'update_category' or 'delete_category' by indicating creation rather than modification or deletion. However, it doesn't explicitly differentiate from 'list_categories' or 'get_category' beyond the verb, 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?
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., if a category already exists), or direct alternatives like 'update_category' for modifications. The description is purely functional without contextual usage 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 full burden for behavioral disclosure. 'Enroll' implies a write operation, but the description doesn't mention permission requirements, whether enrollment is reversible, what happens on duplicate enrollment attempts, or what the tool returns. 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 that gets straight to the point with no wasted words. It's perfectly front-loaded and appropriately sized for this tool's 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 no annotations and no output schema, the description is inadequate. It doesn't explain what happens after enrollment, what errors might occur, or how this differs from similar enrollment tools. The agent lacks crucial context 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, meeting the baseline expectation but not providing extra 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 ('Enroll') and target ('a user in a course'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'create_bundle_enrollment' or 'update_enrollment', but the verb+resource combination is specific enough 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 'create_bundle_enrollment' or 'update_enrollment'. There's no mention of prerequisites, constraints, or typical use cases, leaving the agent with minimal contextual 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 provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention required permissions, whether this triggers notifications or workflows, what happens on duplicate attempts, or what the expected 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without unnecessary words. It's appropriately sized for a tool with clear parameters and no complex behavioral nuances to explain.
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 and no output schema, the description is inadequate. It doesn't explain what happens after creation (e.g., does it return an order ID?), what validation occurs, or potential error conditions. The presence of sibling 'purchase_external_order' and 'refund_external_order' tools suggests this is part of a workflow that isn't documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain relationships between parameters, provide examples, or clarify edge cases. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('create') and resource ('external order') with specific context ('for purchases made outside Thinkific'), which distinguishes it from generic order creation tools. However, it doesn't explicitly differentiate from the sibling 'purchase_external_order' tool, which appears to serve a related function.
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 'purchase_external_order' or 'create_enrollment'. It mentions the context ('for purchases made outside Thinkific') but doesn't specify prerequisites, constraints, or when other tools might be more 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. While 'Create' implies a mutation, the description lacks details on permissions required, whether the operation is idempotent, error handling, or what the response includes (e.g., group ID). 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.
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 front-loaded with essential information. It efficiently communicates the core 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 tool's complexity as a mutation with no annotations and no output schema, the description is insufficient. It fails to address behavioral aspects like side effects, return values, or error conditions, leaving critical gaps for an AI agent to understand how to use it 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 input schema has 100% description coverage, with the single parameter 'name' documented as 'Group name'. The description does not add any additional semantic context beyond what the schema provides, such as naming conventions or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Create') and resource ('a new group on the Thinkific site'), making the purpose immediately understandable. However, it does not differentiate from sibling tools like 'create_user' or 'create_category' beyond specifying the resource type, which is adequate but not exceptional.
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_user' or 'gql_bulk_add_users_to_groups', nor does it mention prerequisites, exclusions, or contextual cues. It merely states what the tool does without operational 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 'Create' which implies a write/mutation operation, but doesn't address permissions needed, whether the operation is idempotent, what happens on duplicate emails, or what the response contains. This leaves significant behavioral gaps for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized and 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?
For a creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation (e.g., returns instructor ID), error conditions, or how it differs from similar creation tools. The context signals indicate complexity (6 parameters) that warrants more guidance than provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so all parameters are documented in the structured schema. The description adds no additional parameter semantics beyond what's in the schema (e.g., no explanation of slug uniqueness or email validation). Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Create') and resource ('instructor profile'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'create_user' or 'create_category' beyond the resource type, 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?
The description provides no guidance on when to use this tool versus alternatives like 'create_user' or 'update_instructor', nor does it mention prerequisites, exclusions, or specific contexts. It's a bare statement of function with no 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 but only states the basic action. It fails to disclose critical behavioral traits such as required permissions, whether creation is idempotent, error handling, or what happens on success (e.g., returns an ID). For a mutation tool, 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 that front-loads the core purpose ('Create a new site script') and adds clarifying context ('custom JS/CSS snippet') without waste. 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 (a mutation with 4 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, or return values, leaving the agent with insufficient context to use the tool effectively beyond basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing clear documentation for all parameters. The description adds no additional parameter semantics beyond implying 'content' is for JS/CSS and 'location' for injection, which is already covered in schema descriptions. This meets the baseline for high schema coverage without extra 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 ('Create') and resource ('site script') with additional context about what it is ('custom JS/CSS snippet'). It distinguishes from siblings like 'update_site_script' and 'delete_site_script' by specifying creation. However, it doesn't explicitly contrast with 'get_site_script' or 'list_site_scripts', keeping 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?
No guidance is provided on when to use this tool versus alternatives like 'update_site_script' for modifications or 'delete_site_script' for removal. The description implies usage for new scripts but lacks explicit conditions, prerequisites, or comparisons to sibling tools, offering 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 the full burden of behavioral disclosure. It states the tool creates a user, implying a write operation, but doesn't cover critical aspects like authentication requirements, rate limits, side effects (e.g., email sending), or error handling. 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 that directly states the tool's purpose without any fluff or redundancy. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place, 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral traits like permissions, side effects, or response format, which are crucial for safe and effective use. Given the complexity of user creation and the lack of structured metadata, the description should provide more context 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 input schema has 100% description coverage, so the schema fully documents all 7 parameters. The description adds no additional parameter semantics beyond what's in the schema, such as explaining interactions between parameters or providing examples. This meets the baseline of 3 when the schema does the heavy lifting.
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 ('Create') and resource ('new user/student on the Thinkific site'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'add_user_to_group' or 'gql_bulk_add_users_to_groups', which would require a more specific scope statement to earn 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. There's no mention of prerequisites (e.g., required permissions), when not to use it, or how it differs from related tools like 'update_user' or 'delete_user' in the sibling list. This leaves the agent without contextual 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 the action without behavioral details. It doesn't disclose if deletion is permanent, requires specific permissions, affects associated products, or has rate limits, leaving significant gaps 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, clear sentence with zero wasted words, efficiently conveying the core purpose without unnecessary elaboration. It's appropriately sized and front-loaded.
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 behavioral context (e.g., permanence, side effects) and usage guidelines, making it inadequate despite the simple parameter schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'category_id' fully documented in the schema. The description adds no additional parameter semantics beyond implying deletion targets a category, so it meets the baseline for high 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 ('Delete') and target resource ('a category from the Thinkific site'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'delete_coupon' or 'delete_group' beyond the resource type, 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 (e.g., category must exist), exclusions, or related tools like 'create_category' or 'update_category' 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?
With no annotations provided, the description carries full burden but only states the action without behavioral details. It doesn't disclose if deletion is permanent, requires admin permissions, affects associated users, or has rate limits, which are critical 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, direct sentence with zero wasted words, front-loading the core action and resource. It's appropriately sized for a simple 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?
For a destructive tool with no annotations and no output schema, the description is incomplete. It lacks critical context like irreversible effects, error conditions, or what happens post-deletion, leaving significant gaps for safe 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 100% with one parameter 'group_id' well-documented in the schema. The description adds no additional parameter semantics beyond implying the group must exist, so it meets the baseline for high schema coverage without extra 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 ('Delete') and resource ('a group from the Thinkific site'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_category' or 'delete_user' beyond specifying the resource type, missing explicit 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. It doesn't mention prerequisites (e.g., group must exist), consequences (e.g., irreversible deletion), or related tools like 'get_group' for verification, 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 provided, the description carries full burden but only states the action without disclosing behavioral traits. It doesn't mention if deletion is permanent, requires specific permissions, has side effects, or returns confirmation, 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, direct sentence with zero wasted words, making it highly concise and front-loaded. Every word earns its place by clearly stating the tool's core function.
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 crucial context like deletion permanence, error conditions, or response format, leaving significant gaps in understanding the tool's behavior and outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'script_id' fully documented in the schema. The description adds no additional meaning beyond what the schema provides, so it meets the baseline of 3 without compensating or enhancing 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 ('Delete') and target resource ('a site script'), which is specific and unambiguous. However, it doesn't distinguish this tool from other deletion tools like delete_category or delete_user, missing 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. It doesn't mention prerequisites (e.g., needing an existing script_id), exclusions, or related tools like get_site_script or update_site_script, 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 provided, the description carries full burden for behavioral disclosure. It states the action is 'Delete' which implies a destructive mutation, but doesn't specify if this is reversible, requires admin permissions, affects related data (e.g., enrollments), or what happens on success/failure. This is inadequate for a destructive operation 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 that directly states the tool's function without unnecessary words. It's front-loaded and wastes no space, 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 and no output schema, the description is insufficient. It doesn't cover behavioral aspects like irreversibility, permission requirements, side effects, or response format, leaving critical gaps for safe agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'user_id' well-documented in the schema. The description adds no additional parameter context beyond implying a user is targeted, so it meets the baseline for high schema coverage without compensating 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 ('Delete') and resource ('a user from the Thinkific site'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'delete_category' or 'delete_group' beyond the resource type, 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?
The description provides no guidance on when to use this tool versus alternatives like 'update_user' or 'list_users', nor does it mention prerequisites or consequences. It's a basic statement of function without contextual usage 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 full burden for behavioral disclosure. While 'deny' implies a write/mutation operation, the description doesn't specify whether this action is reversible, what permissions are required, what happens to the denied request, or any side effects. It provides only the basic action without 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, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a simple action tool and front-loads 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?
For a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what happens after denial, whether the action is logged, what response to expect, or any error conditions. The agent lacks important contextual information needed 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 100%, with both parameters ('request_id' and 'reason') well-documented in the schema. The description doesn't add any parameter-specific information beyond what the schema already provides, so it meets the baseline for high schema coverage without compensating 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 ('deny') and resource ('product publish request'), making the purpose unambiguous. It distinguishes from sibling 'approve_publish_request' by specifying the opposite action, though it doesn't explicitly mention this sibling relationship in the description text itself.
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., that a publish request must exist), when denial is appropriate, or refer to the sibling 'approve_publish_request' tool for comparison. The agent must infer usage context 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 'gets' information, implying a read-only operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or what 'detailed information' includes. 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, efficient sentence that front-loads the core purpose ('Get detailed information') without any wasted words. It's appropriately sized for a simple lookup tool and earns its place by clearly stating the action and key constraint.
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 and no output schema, the description is incomplete for a tool that presumably returns complex bundle data. It doesn't explain what 'detailed information' includes, potential response formats, or error handling. For a read operation in a context-rich environment with many siblings, this leaves too much unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'bundle_id' fully documented in the schema. The description adds no additional semantic context beyond implying the ID is required for lookup. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to heavily.
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 ('Get') and resource ('detailed information about a specific bundle by ID'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'list_bundles' or 'gql_bundle', but the specificity of 'by ID' implies a single-item retrieval versus listing 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?
The description provides no guidance on when to use this tool versus alternatives like 'list_bundles' or 'gql_bundle'. It mentions 'by ID' which implies a prerequisite of having a bundle ID, but offers no explicit usage context, exclusions, or comparisons to sibling 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?
No annotations are provided, so the description carries full burden. It states this is a read operation ('Get'), but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or what 'detailed information' includes. 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 core purpose without unnecessary words. It's appropriately sized for a simple retrieval tool, 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 the complexity (a read operation with no output schema and no annotations), the description is incomplete. It doesn't explain what 'detailed information' returns, potential errors, or usage context relative to siblings. For a tool in a server with many alternatives, more guidance is needed to ensure correct agent selection.
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 100%, with the parameter 'category_id' documented as 'The category ID' in the schema. The description adds no additional meaning beyond this, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
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 ('Get detailed information') and resource ('about a specific category by ID'), making the purpose understandable. It doesn't explicitly distinguish from sibling tools like 'list_categories' or 'gql_category', but the focus on a single category by ID is reasonably clear.
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 'list_categories' (for multiple categories) or 'gql_category' (for GraphQL queries). The description implies usage for retrieving details of a known category ID, 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 the tool retrieves 'detailed information,' which implies a read-only operation, but doesn't specify permissions, rate limits, error conditions, or what 'detailed information' entails (e.g., fields returned, format). For a tool with 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.
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 purpose ('Get detailed information'), making it easy to parse quickly. Every part of the sentence contributes directly to understanding the tool's function.
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 for a tool that likely returns complex educational content data. It doesn't explain what 'detailed information' includes, potential authentication needs, or how it differs from similar sibling tools. For a read operation in a rich domain, this leaves too much unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'content_id' well-documented in the schema itself. The description adds minimal value by mentioning 'by ID,' which is already implied by the schema, but doesn't provide additional context like ID format or examples. This meets the baseline for high 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 tool's purpose with a specific verb ('Get') and resource ('detailed information about a specific content/lesson'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_course', 'get_chapter', or 'gql_lesson', which appear to retrieve similar educational 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. With many sibling tools that retrieve educational content (e.g., 'get_course', 'get_chapter', 'gql_lesson'), there's no indication of how this tool differs in scope or when it's the appropriate choice, leaving the agent to guess based on 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 full burden. It states this is a read operation ('Get'), implying it's non-destructive, but doesn't disclose any behavioral traits such as authentication requirements, rate limits, error handling, or what 'detailed information' entails. This leaves significant gaps for an agent to understand how to use it 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, efficient sentence that directly states the tool's purpose without unnecessary 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 and output schema, the description is incomplete. It doesn't explain what 'detailed information' includes, how results are structured, or any behavioral aspects like permissions or errors. For a retrieval tool in a complex system with many siblings, this leaves too much undefined 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?
The schema description coverage is 100%, with the parameter 'course_id' fully documented in the schema. The description adds no additional semantic context beyond implying the tool requires a course ID, which is already clear from the schema. This meets the baseline score when schema coverage is high.
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 ('Get') and resource ('detailed information about a specific course'), making the purpose unambiguous. However, it doesn't differentiate from similar sibling tools like 'gql_course' or 'gql_course_by_slug', which appear to serve similar retrieval functions, 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 'gql_course' and 'gql_course_by_slug' that likely retrieve course data differently, there's no indication of context, prerequisites, or trade-offs for choosing this specific tool.
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 a review but doesn't cover aspects like authentication requirements, error handling (e.g., what happens if the ID doesn't exist), rate limits, or the format of the returned data. This leaves significant gaps for a read 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—a single sentence that directly states the tool's function without unnecessary words. It's front-loaded and wastes no space, making it efficient 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 the lack of annotations and output schema, the description is insufficient for a complete understanding. It doesn't explain what data is returned (e.g., review content, ratings, timestamps) or behavioral aspects like permissions or errors. For a tool with no structured output documentation, this leaves the agent poorly 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?
The schema description coverage is 100%, with the single parameter 'review_id' fully documented in the schema as an integer greater than 0. The description adds minimal value beyond this, merely restating that it retrieves by ID without providing additional context like ID format or examples.
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 ('Get') and resource ('a specific course review by ID'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'list_course_reviews' or 'create_course_review', but the specificity of retrieving a single item by ID is reasonably 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_course_reviews' for multiple reviews or 'create_course_review' for adding reviews, nor does it specify prerequisites or 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves detailed information, implying a read-only operation, but doesn't mention potential constraints like authentication requirements, rate limits, error conditions, or the format of returned data. 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, efficient sentence that directly states the tool's purpose without unnecessary 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 and output schema, the description is incomplete. It doesn't explain what 'detailed information' includes, how errors are handled, or any prerequisites. For a read operation in a system with many sibling tools, 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?
The input schema has 100% description coverage, with the parameter 'instructor_id' documented as 'The instructor ID' with type and constraints. The description adds no additional meaning beyond this, such as examples or context for valid IDs, so it meets the baseline score of 3 where the schema does the heavy lifting.
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 ('Get') and resource ('detailed information about a specific instructor'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'list_instructors' or 'gql_instructor', which could provide similar functionality, 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 such as 'list_instructors' for multiple instructors or 'gql_instructor' for GraphQL-based queries. It lacks explicit when/when-not instructions or named alternatives, 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 provided, the description carries the full burden of behavioral disclosure. It states it retrieves 'detailed information' but doesn't specify what that includes, whether it's a read-only operation, potential error conditions, or any rate limits. This leaves significant gaps in understanding how the tool behaves beyond basic 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, clear sentence that efficiently conveys the core functionality without any wasted words. It's front-loaded with the essential 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?
For a retrieval tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'detailed information' includes, the format of the response, or any behavioral nuances. Given the lack of structured data, the description should provide more context to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'by ID' which aligns with the 'product_id' parameter in the schema. Since schema description coverage is 100%, the schema already documents this parameter fully. The description adds minimal value beyond what the schema provides, meeting the baseline for high 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 verb ('Get') and resource ('detailed information about a specific product'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'gql_product' or 'list_products' which might serve similar 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 like 'gql_product' or 'list_products'. It lacks any context about prerequisites, limitations, or specific scenarios where this tool is preferred over others, 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Get' implies a read-only operation, the description doesn't specify whether this requires authentication, what happens if the promotion ID doesn't exist, or what format the detailed information returns. 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and 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 lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' includes, how errors are handled, or any authentication requirements. For a tool that presumably returns structured promotion data, more context about the return format would be 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 input schema has 100% description coverage, with the single parameter 'promotion_id' clearly documented as an integer greater than 0. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline score of 3 for high 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 verb ('Get') and resource ('detailed information about a specific promotion'), making the purpose unambiguous. However, it doesn't explicitly differentiate from its sibling 'get_promotion_by_coupon', which appears to serve a similar purpose but uses a different identifier.
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 'get_promotion_by_coupon' or 'list_promotions'. It mentions the required 'promotion_id' parameter but doesn't explain how to obtain it or when this tool is preferred over other promotion-related 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 full burden for behavioral disclosure. It only states the basic operation without mentioning whether this is a read-only query, what permissions are required, error handling for invalid IDs, or the format of returned data. This leaves significant gaps for a tool that likely fetches sensitive 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 that directly states the tool's purpose without any unnecessary words. It's perfectly front-loaded and wastes no space.
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 data retrieval tool with no annotations and no output schema, the description is insufficient. It doesn't explain what information the publish request contains, how results are structured, or potential error conditions. Given the complexity implied by sibling tools like 'approve_publish_request', more context about the returned object would be valuable.
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 100%, with the single parameter 'request_id' fully documented in the schema. The description adds no additional parameter information beyond what's already in the structured data, so it meets the baseline for adequate but unenhanced 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 ('Get') and resource ('a specific product publish request by ID'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_publish_requests' or 'approve_publish_request', 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 'list_publish_requests' for browsing or 'approve_publish_request' for actions. It simply states what the tool does without context about appropriate 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 the full burden of behavioral disclosure. While 'Get' implies a read-only operation, the description doesn't specify authentication requirements, rate limits, error conditions, or what constitutes 'detailed information' in the response. 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, efficient sentence that immediately states the tool's core function without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the essential information, making it easy for an agent 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 and output schema, the description is insufficiently complete. It doesn't explain what 'detailed information' includes, how errors are handled, or any prerequisites for use. For a tool in a context with many similar alternatives and no structured output documentation, more contextual guidance 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?
Schema description coverage is 100%, so the schema already fully documents the single parameter 'user_id'. The description adds no additional semantic context about the parameter beyond what's in the schema (e.g., format examples, valid ranges beyond exclusiveMinimum: 0, or how IDs are obtained). This meets the baseline for high 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 tool's purpose with a specific verb ('Get') and resource ('detailed information about a specific user'), making it immediately understandable. However, it doesn't differentiate itself from sibling tools like 'gql_user' or 'gql_user_by_email', which appear to serve similar user 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. With sibling tools like 'gql_user', 'gql_user_by_email', and 'search_users' available, there's no indication of how this tool differs in scope, input requirements, or output format, leaving the agent to guess about appropriate usage 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 for behavioral disclosure. It states the action is a 'bulk add' which implies a write/mutation operation, but doesn't specify permissions required, whether it's idempotent, error handling for partial failures, rate limits, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves critical behavioral aspects undocumented.
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 includes the GraphQL implementation detail. Every word earns its place, making it highly concise while still 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?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens on success/failure, return values, error conditions, or system impacts. The 100% schema coverage helps with inputs, but the overall context for using this tool remains incomplete, especially given its potentially destructive nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters ('userIds' and 'groupIds') clearly documented in the schema. The description adds no additional parameter semantics beyond what the schema provides—it doesn't explain format expectations, constraints, or relationships between the arrays. Baseline score of 3 is appropriate when the schema does the heavy lifting.
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 ('bulk add'), the target resources ('multiple users to multiple groups'), and the implementation method ('GraphQL'). It distinguishes from the simpler 'add_user_to_group' sibling tool by emphasizing bulk operations. However, it doesn't specify what 'bulk' means quantitatively or how it differs from other bulk operations like 'bulk_create_coupons'.
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_user_to_group' for single operations or other bulk tools. It doesn't mention prerequisites, constraints, or typical use cases. The only implied context is the need for bulk operations, but 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 provided, the description carries full burden but only states the operation type. It doesn't disclose permissions required, whether removal is reversible, error handling for invalid IDs, rate limits, or what happens if users aren't in specified groups. For a destructive bulk 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?
Single sentence with zero wasted words. Front-loaded with the core action and scope, efficiently conveying the essential 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 destructive bulk mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or behavioral constraints. The combination of high-risk operation and minimal description creates 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 100%, with both parameters clearly documented in the schema. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline for high 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 ('bulk remove') and resources ('multiple users from multiple groups'), with the GraphQL context specified. It distinguishes from simpler operations like 'remove_user_from_group' but doesn't explicitly differentiate from sibling 'gql_bulk_add_users_to_groups' beyond the verb 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?
No guidance on when to use this tool versus alternatives like 'remove_user_from_group' or 'delete_user'. The description implies bulk operations but doesn't specify thresholds or prerequisites for using bulk versus individual 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 the tool returns a bundle, implying a read-only operation, but lacks details on authentication needs, error handling, rate limits, or response format. 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 extremely concise and front-loaded, consisting of a single sentence that directly states the tool's purpose. There is no wasted language, making it efficient and easy to parse, 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 lack of annotations and output schema, the description is incomplete. It doesn't explain what a 'Bundle' entails, the return format, or how this tool differs from similar siblings. For a read operation in a context 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 100%, with the single parameter 'id' documented as 'The bundle ID'. The description adds no additional meaning beyond this, such as format examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.
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 ('Returns') and resource ('a Bundle by ID'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_bundle' or 'list_bundles', which appear to serve similar purposes, 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. With sibling tools like 'get_bundle' and 'list_bundles' available, there's no indication of context, prerequisites, or differences (e.g., GraphQL vs. REST, performance, 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?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a read operation ('Returns'), which is helpful, but doesn't mention authentication requirements, rate limits, error conditions, or what format the chapter data comes in. 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 extremely concise - a single sentence that communicates the core functionality without any wasted words. It's front-loaded with the essential information and earns its place 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?
Given the tool has no annotations and no output schema, the description should provide more context about what data is returned, authentication requirements, and how this differs from similar tools. The current description is too minimal for a tool that presumably returns structured chapter data through a GraphQL interface.
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 ('by ID') which aligns with the single 'id' parameter in the schema. With 100% schema description coverage, the schema already documents this parameter well, so the description adds minimal value beyond what's in the structured data. This meets the baseline for high 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 ('Returns') and resource ('a Chapter by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_chapter' or 'list_chapters' beyond mentioning GraphQL, which is helpful but not fully distinguishing.
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 'get_chapter' or 'list_chapters'. It mentions GraphQL, but doesn't explain why one would choose this GraphQL-based tool over other query methods, 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 of behavioral disclosure. It states the tool is for finding a community, implying a read-only operation, but doesn't cover aspects like error handling (e.g., what happens if the ID is invalid), authentication needs, rate limits, or response format, which are critical for a GraphQL-based 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 ('Find a community by ID') and includes the method ('GraphQL') concisely, 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 lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., community details or an error), behavioral traits like side effects, or how it fits into the broader GraphQL context with siblings, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'The community ID'. The description adds no additional semantic details beyond this, such as ID format or examples, so it meets the baseline for high schema coverage without extra 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 ('Find') and resource ('a community by ID'), making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'gql_group' or 'gql_space' that might also retrieve community-related data, 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. It doesn't mention prerequisites, such as needing a valid community ID, or compare it to similar tools like 'gql_group' or 'gql_space' for community retrieval, 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 the full burden of behavioral disclosure. It states it's a read operation ('Returns'), implying it's likely safe and non-destructive, but doesn't cover aspects like authentication needs, rate limits, error handling, or response format. This leaves significant gaps in understanding how the tool behaves beyond its basic function.
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 directly states the tool's function without any unnecessary words. It's front-loaded with the core action, making it efficient and easy to parse, though this 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 lack of annotations and output schema, the description is incomplete. It doesn't explain what a 'Course' entails in this context, how the GraphQL aspect affects usage, or what the return values look like. For a tool with no structured behavioral data, this minimal description fails to provide sufficient context for 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 input schema has 100% description coverage, with the 'id' parameter clearly documented. The description adds minimal value by mentioning 'by ID', which is already implied by the schema. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't provide additional semantic context beyond what's in the structured data.
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 ('Returns') and resource ('a Course by ID'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_course' or 'gql_course_by_slug', which likely serve similar purposes but with different parameters 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention why one would choose GraphQL over other methods (e.g., 'get_course'), or specify any prerequisites or contexts for its use, leaving the agent without clear 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 this is a read operation ('Returns'), which is helpful, but lacks critical details: it doesn't specify authentication requirements, rate limits, error handling (e.g., what happens if the slug doesn't exist), or the structure of the returned Course object. 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 extremely concise—a single sentence that efficiently conveys the core functionality. It's front-loaded with the key action and resource, with no wasted words. This brevity is appropriate for a simple lookup tool, though it comes at the cost of completeness 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?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what a 'Course' object contains, how errors are handled, or any dependencies (e.g., authentication). Given the complexity implied by GraphQL and the lack of structured metadata, more context is needed to fully understand the tool's operation and results.
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 100%, with the 'slug' parameter fully documented in the schema. The description adds minimal value beyond this, only reinforcing that the tool operates 'by slug'. It doesn't provide examples of valid slug formats, constraints, or how slugs relate to other identifiers. Given the high schema coverage, a baseline score of 3 is appropriate.
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 ('Returns') and resource ('a Course by slug'), making the purpose understandable. It distinguishes this as a GraphQL variant, which helps differentiate it from non-GraphQL siblings like 'get_course'. However, it doesn't explicitly contrast with 'gql_course' (which likely returns a course by ID), leaving some ambiguity about when to use this specific slug-based query.
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 'by slug' and 'GraphQL', but doesn't explain when to prefer this over 'get_course' (which might use REST) or 'gql_course' (which might use a different identifier). There's no mention of prerequisites, error conditions, 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 for behavioral disclosure. It states it's a creation tool (implying mutation) but doesn't mention required permissions, whether it's idempotent, rate limits, error conditions, or what happens on success. The GraphQL note adds some context but doesn't cover critical behavioral traits for a mutation 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 brief (two sentences) and front-loaded with the main purpose. The GraphQL note and parameter clarification are relevant additions. No wasted words, though it could be slightly more structured with bullet points or clearer separation of concerns.
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 and no output schema, the description is insufficient. It doesn't explain what the tool returns, error handling, authentication requirements, or side effects. The 100% schema coverage helps with inputs, but the overall context for safe and effective use is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (spaceId, title, body) with clear descriptions. The description adds marginal value by noting that 'CreatePostInput uses content for the body', which clarifies potential terminology confusion but doesn't significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a community post') and resource ('in a space'), which is specific and unambiguous. It distinguishes from siblings like 'gql_reply_to_post' or 'gql_update_post' by focusing on initial creation. However, it doesn't explicitly differentiate from other creation tools like 'create_category' or 'create_user', which slightly limits 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 mentions GraphQL context but doesn't explain why to choose this over non-GraphQL tools or other post-related tools like 'gql_reply_to_post'. There are no prerequisites, exclusions, or comparative context 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 mentions the outcome ('receive notifications') but lacks details on permissions required, rate limits, whether the action is reversible, error conditions, 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 a single, efficient sentence that front-loads the key action and purpose without unnecessary words. It effectively communicates the tool's function in a minimal format, earning its place 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 the tool's complexity as a mutation (implied by 'Follow'), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like side effects, authentication needs, or return values, making it inadequate for safe and effective use by an AI agent in this 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 100%, with the parameter 'postId' documented as 'The post ID to follow'. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
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 ('Follow') and resource ('a post'), specifying it's for receiving notifications and uses GraphQL. It distinguishes from siblings like 'gql_unfollow_post' by being the opposite action, though not explicitly mentioned. However, it doesn't fully differentiate from other post-related tools like 'gql_pin_post' or 'gql_react_to_post' in terms of purpose.
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 implies usage for notification purposes but doesn't mention prerequisites (e.g., authentication), when not to use it, or compare it to similar tools like 'gql_unfollow_post' or other post-interaction 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 'Returns' data, implying a read-only operation, but doesn't specify if it requires authentication, has rate limits, or details the return format. This is inadequate for a 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 extremely concise with a single sentence that directly states the tool's function. It is front-loaded and wastes no words, 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 and output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral traits like authentication needs. For a read operation in a context with many sibling tools, 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 100%, so the input schema already documents the 'id' parameter fully. The description adds no additional meaning beyond implying the tool fetches a group, which is redundant with the schema. Baseline 3 is appropriate as the schema handles 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 ('Returns') and resource ('a Group by ID'), making the purpose understandable. However, it doesn't distinguish this GraphQL-based tool from its sibling 'get_group', which likely serves a similar purpose through a different API, 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?
No guidance is provided on when to use this tool versus alternatives like 'get_group' or other GraphQL siblings. The description lacks context about prerequisites, when-not scenarios, or explicit comparisons, 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 the full burden of behavioral disclosure. It states it's a read operation ('Returns'), but doesn't mention permissions, error handling, rate limits, or what the return format looks like. For a GraphQL-based tool with 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.
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 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 of a GraphQL-based retrieval tool with no annotations and no output schema, the description is incomplete. It lacks details on return values, error cases, or how it differs from similar tools, making it insufficient for an agent to fully understand the tool's behavior and 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 100%, with the 'id' parameter fully documented in the schema. The description adds no additional parameter details beyond implying it's for a Lesson ID, which is already covered. This meets the baseline of 3 since the schema does the heavy lifting.
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 ('Returns') and resource ('a Lesson by ID'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from similar sibling tools like 'gql_view_lesson' or 'get_content', which might also retrieve lesson-related data, leaving some ambiguity about uniqueness.
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 'gql_view_lesson' and 'get_content' that might overlap in functionality, there's no indication 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 the mutation action ('Mark as incomplete') but lacks critical behavioral details: whether this requires specific permissions, if it's reversible, what happens to progress data, or error conditions. 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 zero waste. It's front-loaded with the core action and includes the GraphQL context concisely. 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks behavioral context (permissions, side effects), usage guidance, and output expectations. While concise, it doesn't compensate for the missing structured information needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'lessonId' documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., format examples, ID sources). Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Mark a lesson as incomplete') and target resource ('for a user'), with the GraphQL context noted. It distinguishes from siblings like 'gql_view_lesson' or 'gql_update_assignment_submission' by focusing on marking incomplete status, but doesn't explicitly contrast with potential alternatives like 'mark_lesson_complete' if they existed.
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., user authentication, lesson existence), exclusions, or related tools like 'gql_view_lesson' for checking status first. Usage is implied only by the action itself.
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 'Move' implies a mutation operation, the description doesn't specify whether this requires specific permissions, if it's reversible, what happens to the post in the original space, or potential side effects (e.g., notifications, access changes). For a mutation tool with zero annotation coverage, this leaves critical behavioral traits undocumented.
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 immediately conveys the core action without unnecessary words. It's front-loaded with the key verb ('Move') and resource, and the parenthetical '(GraphQL)' provides useful technical context without cluttering the main message. Every element 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 and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, or error conditions, nor does it describe the return value or success indicators. While the schema covers parameters well, the overall context for safe and effective use is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both postId and spaceId parameters. The description adds no additional parameter semantics beyond what's in the schema—it doesn't explain format requirements, validation rules, or relationships between parameters. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema does the heavy lifting.
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 ('Move') and resource ('a post'), and specifies the destination ('to a different space'). It distinguishes this from sibling tools like gql_create_post or gql_update_post by focusing on relocation rather than creation or modification. However, it doesn't explicitly differentiate from other post-related tools like gql_pin_post or gql_follow_post in terms of purpose.
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 post and space IDs), exclusions (e.g., not for moving other resources), or compare it to similar tools like gql_update_post (which might handle post content changes). Without this 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 full burden for behavioral disclosure. It states the action ('Pin') which implies a mutation, but doesn't specify required permissions, whether the operation is reversible, rate limits, or what happens if the post is already pinned. 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 with a single sentence that states the core purpose. There's no wasted language or unnecessary elaboration, making it efficiently front-loaded 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?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'pinning' means operationally, what the expected outcome is, error conditions, or how this differs from related tools like 'gql_unpin_post'. The agent lacks critical context for proper 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 schema has 100% description coverage, with the single parameter 'postId' clearly documented in the schema. The description doesn't add any parameter information beyond what's already in the schema, so it meets the baseline of 3 but doesn't provide additional semantic 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 ('Pin') and resource ('a post in its space'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'gql_unpin_post' or explain what 'pinning' means in this context, 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 'gql_unpin_post' or 'gql_move_post'. It doesn't mention prerequisites (e.g., needing post ID) or contextual constraints (e.g., permissions required), leaving the agent with minimal 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 full burden. It mentions GraphQL but doesn't disclose behavioral traits like whether it's read-only, error handling, authentication needs, or rate limits. For a tool with no annotations, 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 that front-loads the purpose ('Find a post or reply by ID') and adds necessary context ('GraphQL') without waste. Every word earns its place, making it appropriately sized and 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 no annotations, no output schema, and a simple input schema, the description is incomplete. It doesn't explain what the tool returns, error conditions, or how it fits into the broader context of sibling tools. For a retrieval tool in a complex server, 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?
Schema description coverage is 100%, with the parameter 'id' fully documented in the schema. The description adds minimal value by implying the ID is for a post or reply, but doesn't provide additional semantics beyond what the schema already states. Baseline 3 is appropriate given high 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 ('Find') and resource ('a post or reply'), specifying it's by ID using GraphQL. It distinguishes from siblings like 'gql_create_post' or 'gql_update_post' by focusing on retrieval, but doesn't explicitly differentiate from other get_* tools that might also fetch posts.
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 'get_content' or other gql_* tools for posts. The description implies it's for finding by ID but doesn't specify context or prerequisites, leaving usage unclear relative to 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?
With no annotations provided, the description carries full burden but only states it 'returns' data without specifying whether this is a read-only operation, what permissions are required, or any rate limits. It doesn't describe the return format, error conditions, or any behavioral traits 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 efficiently front-loaded 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?
For a tool with no annotations and no output schema, the description is insufficient. It doesn't explain what a 'Product' contains, what the GraphQL implementation entails, or provide any context about the data returned. Given the complexity implied by GraphQL and the lack of structured documentation, more completeness 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 schema has 100% description coverage with the 'id' parameter clearly documented. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline for high schema coverage but doesn't enhance understanding of parameter usage 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 ('Returns') and resource ('a Product by ID'), making the purpose understandable. It distinguishes from other product-related tools like 'get_product' by specifying it uses GraphQL, but doesn't fully differentiate from all sibling tools like 'gql_category' or 'gql_user' which follow the same 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 like 'get_product' or other GraphQL siblings. It mentions 'GraphQL' but doesn't explain why one would choose this over REST equivalents or when to use other GraphQL 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?
No annotations are provided, so the description carries full burden. It states this is a GraphQL operation and clarifies parameter mapping ('content' for body, 'parentId' for post ID), but doesn't disclose critical behavioral traits like whether this is a mutation (likely yes), what permissions are required, if it's rate-limited, or what the response looks like. For a write operation 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 brief and front-loaded with the core purpose. The note about parameter mapping is helpful but could be more integrated. No wasted sentences, 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 this is a write operation (replying to a post) with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after the reply (e.g., success response, error handling), permissions needed, or how it differs from other post tools. For a mutation tool in a GraphQL context, more behavioral context is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly documented in the schema. The description adds minimal value by clarifying that 'content' maps to 'body' and 'parentId' maps to 'postId', but this is redundant with the schema. Baseline 3 is appropriate since the schema does the heavy lifting.
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 ('Reply to a post') and the resource ('a post'), making the purpose immediately understandable. However, it doesn't distinguish this tool from other post-related siblings like 'gql_create_post' or 'gql_update_post' beyond the 'reply' action, which is why it doesn't reach 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 'gql_create_post' for new posts or 'gql_update_post' for editing. It mentions GraphQL context but doesn't explain why this specific tool is needed over non-GraphQL options, 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 must fully disclose behavior. It states the tool finds a space by ID but omits critical details: whether it's a read-only operation, what happens if the ID is invalid, if authentication is required, or the return format. For a 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 zero waste. It's front-loaded with the core purpose ('Find a space by ID') and includes a relevant qualifier ('GraphQL'). 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 no annotations and no output schema, the description is incomplete. It doesn't explain what 'find' entails (e.g., returns space details or just existence), error conditions, or authentication needs. For a tool in a complex environment with many siblings, 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?
The schema description coverage is 100%, with the 'id' parameter documented as 'The space ID'. The description adds no additional meaning beyond this, such as ID format or examples. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't detract.
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 'Find a space by ID (GraphQL)' clearly states the action (find) and resource (space), with the GraphQL qualifier distinguishing it from non-GraphQL siblings like 'get_site_info'. However, it doesn't explicitly differentiate from other GraphQL read tools (e.g., 'gql_category', 'gql_user'), 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 space ID), compare it to similar GraphQL tools, or specify use cases. This leaves the agent without context for selection among many sibling 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?
No annotations are provided, so the description carries full burden. It states the action but lacks critical behavioral details: it doesn't specify if this is a reversible operation, what permissions are required, whether it affects notifications or user feeds, or what happens on success/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 extremely concise—a single sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to scan and understand immediately.
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 and no output schema, the description is incomplete. It lacks behavioral context (e.g., side effects, error conditions), usage prerequisites, and output expectations. While concise, it doesn't provide enough information 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'postId' fully documented in the schema. The description adds no additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.
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 ('Unfollow') and resource ('a post'), with the parenthetical '(GraphQL)' providing implementation context. It distinguishes from siblings like 'gql_follow_post' by specifying the opposite action, though it doesn't explicitly contrast with other post-related tools like 'gql_pin_post' or 'gql_move_post'.
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., the post must be currently followed), nor does it differentiate from potential non-GraphQL unfollow methods if they exist. The description assumes context without 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?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the valid statuses but doesn't cover critical aspects like permissions required, whether this is a destructive mutation, rate limits, error conditions, or what happens to the submission after update. The GraphQL context is noted but not explained.
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 to the point with a single sentence. It efficiently communicates the core functionality without unnecessary words, though it could be slightly more informative given the lack of 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?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error handling, side effects, or authentication requirements. The GraphQL context is mentioned but not elaborated, leaving gaps in understanding how 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 100%, so the schema fully documents all three parameters. The description adds minimal value by listing the valid statuses, which the schema's enum already provides. It doesn't explain parameter interactions or provide context beyond what's in the 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 ('Update the status') and resource ('assignment submission'), making the purpose evident. It doesn't explicitly differentiate from sibling tools like 'update_enrollment' or 'update_user', but the specificity of 'assignment submission' and GraphQL context provides some implicit 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., authentication needs), compare to non-GraphQL tools, or specify scenarios where this update is appropriate versus other submission-related 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 it's an update operation, implying mutation, but doesn't cover critical aspects like required permissions, whether changes are reversible, error handling, or rate limits. The mention of GraphQL adds some context, but overall, behavioral traits are inadequately described 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 that front-loads the core action ('Update a post's title and/or content') and includes the GraphQL context. There is no wasted verbiage or redundancy, making it highly 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 tool's complexity as a mutation with no annotations and no output schema, the description is insufficient. It lacks details on behavioral traits, usage context, and expected outcomes. For a tool that modifies data, more completeness is needed to guide the agent effectively, such as explaining what happens on success or failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the three parameters (postId, title, body) with their types and optionality. The description adds minimal value by implying that title and content are updatable fields, but it doesn't provide additional semantics beyond what the schema already states. This meets the baseline for high 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 ('Update') and resource ('post's title and/or content'), making the purpose evident. It specifies the GraphQL context, which distinguishes it from non-GraphQL update tools. However, it doesn't explicitly differentiate from sibling tools like 'gql_update_product' or 'update_user', which share similar update 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid postId), exclusions (e.g., what cannot be updated), or comparisons to siblings like 'gql_create_post' or 'gql_move_post'. The agent must infer usage from the name and schema 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. While 'Update' implies a mutation operation, the description doesn't address important behavioral aspects: whether this requires specific permissions, whether changes are reversible, what happens to unspecified attributes, error conditions, or response format. The status enum information is helpful 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 efficiently structured in a single sentence that conveys the core purpose and key constraint (valid statuses). There's no wasted language, and the most critical information (update operation and status constraints) is front-loaded. The parenthetical '(GraphQL)' adds useful technical context without disrupting the 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?
For a mutation tool with 8 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't address behavioral expectations, error handling, authentication requirements, or what constitutes a successful update. While the schema covers parameter documentation, the description fails to provide the contextual information needed to use this tool effectively 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?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description adds the status enum values (DRAFT, PENDING_APPROVAL, PRESELL, PUBLISHED), which provides context beyond the schema's enum declaration. However, it doesn't explain parameter interactions, dependencies, or provide additional semantic context about how these attributes relate to each other or affect the product.
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 product attributes') and resource ('product'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this GraphQL-based product update from other product-related tools like 'update_product' (which doesn't exist in the sibling list) or 'gql_product' (which appears to be a read operation). The mention of '(GraphQL)' provides some technical context but not clear 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. While it mentions valid statuses, it doesn't indicate prerequisites, when this tool is appropriate versus other update methods, or any constraints on usage. With many sibling tools including other GraphQL operations and product-related functions, the lack of comparative guidance is a significant gap.
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 offers minimal behavioral information. It indicates a read operation ('Returns') but doesn't disclose authentication requirements, rate limits, error behavior (e.g., what happens if email doesn't exist), or response format. For a GraphQL query 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 extremely concise (7 words) and front-loaded with all essential information. Every word earns its place: verb, resource, lookup method, and technology context. There's zero redundancy 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 GraphQL query tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what a 'User' object contains, how errors are handled, authentication requirements, or performance characteristics. The agent lacks critical context needed to use this tool effectively despite its simple parameter structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single well-documented 'email' parameter, so the baseline is 3. The description adds no additional parameter semantics beyond what's in the schema (it merely restates 'by email address'), providing no format examples, validation rules, or edge case handling beyond the schema's email format specification.
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 ('Returns') and resource ('a User'), specifying the lookup mechanism ('by email address') and technology context ('GraphQL'). It distinguishes from generic 'get_user' by specifying the email-based query approach, though it doesn't explicitly differentiate from other user retrieval tools like 'gql_user' or 'search_users'.
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 'gql_user', 'get_user', or 'search_users'. It doesn't mention prerequisites, error conditions, or typical use cases. The agent must infer usage from the name and description alone without explicit 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 the full burden of behavioral disclosure. It states the action ('Record') but doesn't clarify if this is a write operation, what permissions are needed, whether it's idempotent, or what side effects occur (e.g., updating user progress). This is a significant gap for a tool that likely 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.
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 without unnecessary words. It's appropriately sized for a simple tool, though it could be slightly more structured (e.g., by including usage context) to improve clarity 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 lack of annotations and output schema, the description is incomplete for a tool that likely performs a write operation. It doesn't explain what 'recording a view' entails (e.g., increments a counter, logs timestamp), what the expected outcome is, or any error conditions, 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 description coverage is 100%, with the single parameter 'lessonId' well-documented in the schema. The description adds no additional parameter semantics beyond what's already in the schema, so it meets the baseline of 3 without compensating or detracting.
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 ('Record a lesson view') and the resource ('for a user'), making the purpose specific and understandable. However, it doesn't distinguish this tool from potential siblings like 'gql_mark_lesson_incomplete' or other lesson-related tools, which would require explicit 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., user authentication), context (e.g., tracking progress), or exclusions (e.g., not for marking completion). This leaves the agent with insufficient context to make informed 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists courses but omits critical details: whether this is a read-only operation, if it requires authentication, how pagination works (implied by parameters but not explained), or what the output format looks like. 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.
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 without unnecessary words. Every part of the sentence ('List courses within a specific bundle') directly contributes to understanding the tool's function, 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?
For a tool with 3 parameters, no annotations, and no output schema, the description is insufficient. It lacks details on behavioral traits (e.g., read-only status, pagination behavior), output format, error conditions, or usage context. The high schema coverage helps with parameters, but overall completeness is poor given the tool's complexity and missing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (bundle_id, page, limit) with types, constraints, and defaults. The description adds no additional parameter semantics beyond what's in the schema, meeting the baseline for high coverage but not enhancing 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 ('List') and resource ('courses within a specific bundle'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_courses' or 'get_bundle', which could cause confusion about scope or 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?
No guidance is provided on when to use this tool versus alternatives like 'list_courses' or 'get_bundle'. The description lacks context about prerequisites (e.g., needing a valid bundle_id) or exclusions, leaving the agent to 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 but only states the basic action. It doesn't mention whether this is a read-only operation, if it requires authentication, what the return format looks like, or any pagination behavior beyond what's in the schema. For a list operation 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 that communicates the core purpose without any wasted words. It's appropriately sized for a simple list operation and front-loaded with 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 list tool with no annotations and no output schema, the description is insufficient. It doesn't explain what information is returned about bundles, how results are structured, or any behavioral aspects like authentication requirements or error conditions. The agent would need to guess about the tool's behavior beyond basic listing.
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 100%, so the schema already documents both parameters (page and limit) with their types, constraints, and defaults. The description adds no additional parameter information beyond what the schema provides, which meets the baseline expectation when schema coverage is complete.
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 ('List') and resource ('course bundles on the Thinkific site'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'list_bundle_courses' or other list tools, which would require more specificity 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 'list_bundle_courses' or 'get_bundle'. It lacks any context about prerequisites, appropriate scenarios, or exclusions, 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('List products') but fails to describe key behaviors: it does not mention pagination (implied by 'page' and 'limit' parameters but not explained), return format, error handling, or any rate limits. For a read operation with parameters, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence ('List products in a specific category.') that is front-loaded and wastes no words. It efficiently conveys the core purpose without unnecessary elaboration, making it easy to parse and understand at a glance.
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 pagination parameters), lack of annotations, and no output schema, the description is incomplete. It does not explain the return structure (e.g., list of product objects), pagination behavior, or potential errors, leaving the agent with insufficient information to handle the tool effectively beyond basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions in the input schema (e.g., 'category_id' as 'The category ID', 'page' with default 1, 'limit' with range 1-250 and default 25). The description adds no additional semantic context beyond implying category filtering, so it meets the baseline of 3 where the schema does the heavy lifting without extra value from the 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 verb ('List') and resource ('products in a specific category'), making the purpose immediately understandable. However, it does not explicitly differentiate from sibling tools like 'list_products' (which likely lists all products without category filtering) or 'list_related_products' (which might list products related to another product), leaving room for ambiguity in 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. It does not mention sibling tools such as 'list_products' (for unfiltered listing) or 'get_product' (for single product details), nor does it specify prerequisites like needing a valid category ID. This lack of context could lead to misuse or confusion in 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 of behavioral disclosure. While 'List' implies a read-only operation, the description doesn't specify whether this requires authentication, returns paginated results (implied by parameters but not stated), has rate limits, or what the output format looks like. For a tool with 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 a single, efficient sentence that front-loads the core purpose ('List chapters (sections) within a course'). There's no wasted verbiage, and every word serves a clear function in conveying the tool's intent.
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 no annotations and no output schema, the description is insufficient. It doesn't explain what the output contains (e.g., chapter IDs, titles, order), whether results are paginated, or any error conditions. The lack of behavioral context makes 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters (course_id, page, limit) clearly documented in the schema. The description adds no additional parameter semantics beyond what's in the schema, such as explaining the relationship between chapters and courses or clarifying pagination behavior. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('List') and resource ('chapters (sections) within a course'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_chapter' or 'gql_chapter', which appear to retrieve single chapters rather than list multiple chapters within a course.
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 valid course_id), when not to use it, or how it differs from similar tools like 'get_chapter' or 'gql_chapter' 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 the full burden. It states it's a list operation, implying read-only behavior, but doesn't disclose pagination details (implied by 'page' and 'limit' parameters), rate limits, authentication needs, or what the output looks like. This is a significant gap 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 zero waste. 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 no annotations and no output schema, the description is incomplete. It doesn't explain the return format (e.g., list of objects with fields), pagination behavior, or error cases. For a tool with three parameters and likely complex output, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters like 'chapter_id', 'page', and 'limit'. The description adds no additional meaning beyond implying a list operation, meeting the baseline for high schema coverage without extra 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 ('List') and resource ('content/lessons within a chapter'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_chapters' or 'get_content', 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. With many sibling tools (e.g., 'list_chapters', 'get_content', 'gql_lesson'), there's no indication of context, prerequisites, or exclusions, 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?
With no annotations provided, the description carries full burden but reveals almost nothing about behavioral traits. It doesn't mention pagination behavior (implied by parameters but not described), rate limits, authentication requirements, or whether this is a read-only operation. The description is functionally minimal.
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 list operation and front-loads the core purpose immediately.
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 list tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the output looks like (e.g., array of review objects), pagination behavior, or how filtering works. The agent would need to guess about important operational aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter semantics beyond what's in the schema (it mentions optional filtering by course, which the schema already covers with course_id). Baseline 3 is appropriate when the schema does all the 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 ('List') and resource ('course reviews'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_course_review' (singular vs. plural), which could cause confusion about when to use each 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 like 'get_course_review' (singular) or other list tools. It mentions optional filtering by course but doesn't explain when filtering is appropriate or what happens without 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 list operation but doesn't disclose behavioral traits like whether it's paginated (implied by parameters but not stated), rate limits, authentication requirements, or what the return format looks like. The description is minimal and lacks essential context for safe 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 a single, efficient sentence that directly states the tool's purpose without any fluff. It's appropriately sized and front-loaded, with every word contributing to 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 lack of annotations and output schema, the description is incomplete. It doesn't explain the return values, pagination behavior, or any constraints beyond the basic purpose. For a list tool with pagination parameters, more context is needed to use it 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 100%, with both parameters (page and limit) well-documented in the schema. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline score of 3 for high 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 verb ('List') and resource ('custom profile field definitions for the site'), making the purpose unambiguous. However, it doesn't distinguish this tool from other list_* siblings like list_users or list_categories, which follow the same pattern 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 provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, context for listing custom profile fields, or comparison to other tools that might retrieve profile information (e.g., get_user).
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 list operation with filtering. It doesn't disclose pagination behavior (implied by page/limit parameters but not explained), rate limits, authentication requirements, or what happens when no filters are applied. The description is minimal and lacks 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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and includes the key filtering capability. 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?
For a list tool with 5 parameters, 100% schema coverage, but no annotations and no output schema, the description is inadequate. It doesn't explain the return format, pagination behavior, error conditions, or how filtering interacts with pagination. The agent would need to infer too much from the parameter names alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds marginal value by mentioning filtering by user or course, which aligns with query_user_id and query_course_id parameters, but doesn't provide additional context beyond what's in the schema descriptions. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('List') and resource ('enrollments') with optional filtering capabilities. It distinguishes this tool from other list_* tools by specifying the enrollment resource type, though it doesn't explicitly differentiate from 'list_bundle_enrollments' among the 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 provides no guidance on when to use this tool versus alternatives like 'get_enrollment' (for single enrollment) or 'list_bundle_enrollments'. It mentions filtering options but doesn't explain when filtering is appropriate or what happens without filters.
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 list operation. It doesn't disclose pagination behavior (implied by parameters but not explained), rate limits, authentication requirements, or what data is returned. For a list tool with no 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 zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple list operation.
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 list tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'groups' means in this context, what fields are returned, pagination behavior, or error conditions. The agent would need to guess about the response format and operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (page and limit). The description adds no additional parameter context beyond what's in the schema, meeting the baseline for high 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 verb ('List') and resource ('groups on the Thinkific site'), making the purpose immediately understandable. It doesn't distinguish from sibling tools like 'get_group' or 'list_users', but it's specific enough to know what resource is being listed.
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 'get_group' (for single group details) or 'list_users' (for listing users). There's no mention of prerequisites, context, or comparison with sibling 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?
No annotations are provided, so the description carries full burden. 'List orders with optional filtering' implies a read-only operation but doesn't disclose pagination behavior (implied by parameters), rate limits, authentication requirements, or what happens when no filters are applied. The description is too minimal for a tool with 4 parameters and 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 extremely concise at just 5 words. It's front-loaded with the core purpose and wastes no words. Every word earns its place, 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 tool with 4 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain the pagination system (page/limit), filtering logic, return format, or error conditions. The minimal description fails to compensate for the lack of structured metadata, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description mentions 'optional filtering' which aligns with the query_user_id and query_email parameters, but adds no additional semantic context beyond what the schema already provides. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('list') and resource ('orders') with the addition of optional filtering. It distinguishes from other list_* tools by specifying the resource type (orders), though it doesn't explicitly differentiate from 'get_order' which appears to retrieve a single order. The purpose is clear but could be more specific 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. There's no mention of when to use 'list_orders' versus 'get_order' (for single order retrieval) or other filtering tools. No prerequisites, exclusions, or contextual usage information is 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 but only states the basic action. It doesn't mention that this is a read-only operation (implied by 'List'), whether it requires authentication, if there are rate limits, what the output format looks like (no output schema), or if it supports filtering beyond pagination. This leaves significant gaps 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff or redundant information. It's front-loaded with the core action and resource, making it easy to parse and understand immediately.
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 list operation with no annotations and no output schema, the description is too minimal. It doesn't explain what 'products' entail in this context (e.g., courses, bundles, digital downloads), how results are ordered, if there are any filters beyond pagination, or what the return structure looks like. This leaves the agent with insufficient context to use the tool effectively beyond basic pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, fully documenting the 'page' and 'limit' parameters with their types, constraints, and defaults. The description adds no additional parameter information beyond what the schema provides, which is acceptable given the high schema coverage, resulting in the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('products available on the Thinkific site'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_bundles', 'list_courses', or 'get_product', which all retrieve product-related data but with different scopes or filters.
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 siblings like 'get_product' (for single products), 'list_bundle_courses' (for products in bundles), or 'list_category_products' (for filtered lists), leaving the agent to infer usage context from 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?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states it's a list operation (implying read-only), but doesn't disclose pagination behavior (implied by parameters), rate limits, authentication needs, or what the return format looks like. This is inadequate for a tool with 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.
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 purpose and appropriately sized for a simple list 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 tool has parameters (pagination) and no output schema, the description is incomplete. It doesn't explain the paginated nature of results, return format, or error conditions. For a list tool with structured inputs, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (page and limit with defaults). The description adds no additional parameter information beyond what's in the schema, which is acceptable but not additive. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('List') and resource ('all site scripts on the Thinkific site'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_site_script' (singular) or 'create_site_script', 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 doesn't mention when to use 'list_site_scripts' versus 'get_site_script' (for a single script) or other list tools, 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 full burden but offers minimal behavioral insight. It mentions 'all users/students' but doesn't disclose pagination behavior (implied by parameters), authentication requirements, rate limits, or what 'users/students' means in this context. For a list operation with no 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 that states the core purpose without unnecessary words. It's appropriately sized for a simple list operation and gets straight to the point with zero wasted verbiage.
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 list operation with no annotations and no output schema, the description is insufficient. It doesn't explain what data is returned, how results are structured, or important behavioral aspects like pagination defaults. While the schema covers parameters well, the overall context for using this tool remains incomplete.
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 100%, with both parameters ('page' and 'limit') well-documented in the schema itself. The description adds no additional parameter information beyond what's already in the structured schema, so it meets the baseline for adequate but unenhanced 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 ('List all') and resource ('users/students on the Thinkific site'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'search_users' or 'get_user', but the verb+resource combination is specific enough 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?
No guidance is provided about when to use this tool versus alternatives like 'search_users' (for filtered searches) or 'get_user' (for single user retrieval). The description simply states what it does without context about appropriate use cases or limitations.
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 recording action but doesn't clarify if this is a read-only operation, a mutation, whether it requires specific permissions, what happens on success/failure, or any side effects. For a transaction tool, this lack of behavioral context 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 that states the core purpose without unnecessary words. It's appropriately sized for a tool with two parameters and no complex behavioral requirements.
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 transaction recording tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'recording' entails (does it update status? create audit trail?), what gets returned, error conditions, or how this differs from related operations. The context signals show this is a simple tool, but the description lacks necessary completeness for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (order_id and amount_cents) with their types and constraints. The description adds no additional parameter semantics beyond what's in the schema, meeting the baseline expectation when schema coverage is complete.
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 ('Record a purchase transaction') and resource ('for an external order'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'create_external_order' or 'refund_external_order', which would require more specificity about what distinguishes this purchase recording from creation or refund 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?
The description provides no guidance on when to use this tool versus alternatives like 'create_external_order' or 'refund_external_order'. There's no mention of prerequisites, context, or exclusions, 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 'Remove' implies a destructive mutation, it doesn't specify whether this action is reversible, what permissions are needed, whether it affects user access immediately, or what happens if the user isn't currently an analyst. The description lacks critical behavioral context for a mutation 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 zero wasted words. It's appropriately sized for a simple mutation tool and front-loads the core action and target 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 mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after removal, whether there's confirmation or error handling, what the 'analyst' role entails, or how this differs from other group membership tools. The minimal description leaves too many contextual 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?
Schema description coverage is 100%, with both parameters clearly documented in the schema. The description doesn't add any meaningful parameter semantics beyond what's already in the schema - it doesn't explain what constitutes a valid group_id or user_id, or provide context about where these IDs come from. Baseline 3 is appropriate when the schema does the heavy lifting.
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 ('Remove') and target ('a user as an analyst from a group'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'remove_user_from_group' or 'gql_bulk_remove_users_from_groups', but the specificity of 'analyst' role provides some implicit 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 about when to use this tool versus alternatives like 'remove_user_from_group' or 'gql_bulk_remove_users_from_groups'. The description doesn't mention prerequisites, permissions required, or any context about what constitutes an 'analyst' role versus other group memberships.
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 removal operation, implying mutation, but doesn't disclose behavioral traits such as permissions required, whether the removal is reversible, error handling (e.g., invalid IDs), or side effects (e.g., impact on product visibility). The description is minimal and lacks necessary context for safe 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 a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, and the parenthetical clarifies the scope ('collection membership'), making it 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutation nature, lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, reversibility, or response format, leaving significant gaps for an agent to use it correctly in context with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters ('category_id' and 'product_ids'). The description adds no additional semantic context beyond what the schema provides, such as format examples or constraints. Baseline is 3 since the schema does the heavy lifting.
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 ('Remove') and resource ('products from a category'), specifying it affects collection membership. It's specific enough to understand the operation but doesn't explicitly differentiate from sibling tools like 'delete_category' or 'add_products_to_category' beyond the verb 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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., existing category/products), exclusions, or comparisons to sibling tools like 'delete_category' (which might delete the entire category) or 'add_products_to_category' (the inverse operation).
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. While 'Update' implies a mutation operation, the description doesn't address important behavioral aspects like required permissions, whether changes are reversible, what happens to existing data not mentioned, error conditions, or what the response contains. The examples help but don't constitute comprehensive behavioral 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 that communicates the core purpose with helpful examples. There's no wasted language, and the information is front-loaded appropriately. 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?
For a mutation tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't address behavioral implications, error handling, response format, or relationship to sibling tools. The description provides only basic purpose information without the contextual depth needed 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 schema description coverage is 100%, so all parameters are documented in the schema. The description adds marginal value by providing examples ('change expiry, free trial status') that map to specific parameters, but doesn't provide additional semantic context beyond what's already in the schema descriptions. This meets the baseline for high 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 ('Update') and resource ('bundle enrollment'), and provides specific examples of what can be updated ('change expiry, free trial status'). However, it doesn't explicitly differentiate this tool from its sibling 'update_enrollment' or other update tools in the list, 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. There's no mention of prerequisites, when this tool is appropriate versus creating a new enrollment, or how it relates to sibling tools like 'create_bundle_enrollment' or 'update_enrollment'.
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. While it correctly indicates this is a mutation operation ('Update'), it doesn't disclose important behavioral traits like permission requirements, whether changes are reversible, what happens to unspecified fields, error handling, or side effects. The description is minimal and lacks crucial 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 extremely concise - a single sentence with parenthetical examples. Every word earns its place, and the information is front-loaded with the core purpose immediately clear. There's zero wasted verbiage or redundant 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 mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what the tool returns, what happens on success versus failure, or important behavioral constraints. The combination of a mutation operation with zero annotation coverage demands more comprehensive description than what's provided.
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 100%, so the schema already documents all 5 parameters thoroughly. The description mentions three specific use cases ('change expiry date, mark completed, set free trial') that map to three of the parameters, but this adds minimal value beyond what the schema already provides. The baseline of 3 is appropriate given the comprehensive 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 ('Update') and resource ('an enrollment'), and provides specific examples of what can be updated ('change expiry date, mark completed, set free trial'). However, it doesn't explicitly differentiate this tool from its sibling 'update_bundle_enrollment', which appears to serve a similar purpose for bundle enrollments specifically.
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_bundle_enrollment' or 'create_enrollment'. It doesn't mention prerequisites, error conditions, or any context about when this update operation is appropriate versus creating a new enrollment.
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. 'Update' implies mutation, but the description doesn't address critical behavioral aspects: whether this requires specific permissions, what happens to existing data not mentioned in parameters, whether changes are reversible, error conditions, or what the response looks like. 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 that states the core purpose without unnecessary words. It's appropriately sized for a straightforward update operation and gets directly to the point 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?
For a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't address behavioral aspects like permissions, side effects, error handling, or response format. Given the complexity of updating an instructor profile (which likely involves validation rules and business logic), the description should provide more contextual guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters with clear descriptions. The description adds no additional parameter information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the 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 verb ('update') and resource ('instructor's profile'), making the purpose immediately understandable. However, it doesn't differentiate this from sibling tools like 'update_user' or 'create_instructor', which would require more specificity about what distinguishes an instructor profile update from other user-related updates.
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_user' or 'create_instructor'. There's no mention of prerequisites, required permissions, or contextual constraints that would help an agent choose between similar-looking 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 this is an update operation, implying mutation, but doesn't disclose any behavioral traits: it doesn't mention permissions required, whether changes are reversible, what happens to unspecified fields, error conditions, or response format. 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, efficient sentence with zero wasted words. It's front-loaded with the core action ('Update an existing site script') and doesn't include any unnecessary details. 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?
For a mutation tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what happens during update (e.g., partial vs. full updates), doesn't mention error handling or permissions, and provides no context about the script system. The agent lacks crucial information to use this tool effectively beyond basic parameter passing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters with clear descriptions. The description adds no additional parameter information beyond what's in the schema (e.g., it doesn't explain relationships between parameters or provide examples). This meets the baseline of 3 when the schema does the heavy lifting, but doesn't earn higher marks for adding 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 ('Update') and resource ('an existing site script'), making the purpose unambiguous. It distinguishes from sibling tools like 'create_site_script' and 'delete_site_script' by specifying it updates existing scripts rather than creating or deleting them. However, it doesn't specify what aspects of the script are updated, 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. It doesn't mention prerequisites (e.g., needing an existing script ID), when not to use it (e.g., for creating new scripts), or compare it to related tools like 'create_site_script' or 'get_site_script'. The agent must infer usage from the name and 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is an update operation, implying mutation, but lacks critical details: required permissions, whether changes are reversible, how partial updates are handled, error conditions, or what the response contains. 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 zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. 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 the complexity (7 parameters, mutation operation) and lack of annotations or output schema, the description is incomplete. It doesn't address behavioral aspects like side effects, permissions, or response format, leaving the agent with insufficient context to use the tool 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?
Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds no parameter-specific information beyond the generic 'details', providing no additional meaning or context about the parameters' roles or interactions. This meets the baseline for high 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 verb ('update') and resource ('existing user's details'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_user' or 'delete_user' beyond the basic verb difference, nor does it specify what 'details' encompasses compared to other user-related tools.
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., user must exist), exclusions (e.g., cannot update certain fields), or comparisons to siblings like 'create_user' for new users or 'delete_user' for removal. Usage is implied only by the verb 'update'.
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 destructive action ('Delete') but doesn't disclose critical behavioral traits: whether deletion is permanent/reversible, what permissions are required, what happens to associated data (courses, enrollments), or error conditions. For a destructive operation 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 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 and no output schema, the description is incomplete. It doesn't explain what 'Delete' entails behaviorally, what the return value might be (success confirmation, error details), or how it interacts with the system context (e.g., sibling tools like 'create_instructor', 'update_instructor').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'instructor_id' fully documented in the schema. The description doesn't add any parameter details beyond what the schema provides, but with only one parameter and complete schema coverage, a baseline of 4 is appropriate (0 params would be 5).
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 target resource ('an instructor profile'), providing a specific verb+resource combination. It doesn't distinguish from sibling tools like 'delete_user' or 'delete_category', but the resource type is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites, consequences, or relationships to sibling tools like 'get_instructor' (for verification) or 'update_instructor' (for modification instead of 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?
With no annotations provided, the description carries full burden but only states it retrieves information without disclosing behavioral traits like authentication requirements, rate limits, error conditions, or what 'detailed information' includes. It's a basic read operation description with minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose with zero wasted words. Every word earns its place in conveying the essential 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 simple read operation with one parameter fully documented in schema, the description is minimally adequate. However, with no annotations and no output schema, it should ideally provide more context about what 'detailed information' includes or authentication needs. It meets basic requirements 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?
Schema description coverage is 100%, so the schema already fully documents the 'chapter_id' parameter. The description adds no additional meaning beyond what's in the schema (e.g., format examples, ID sourcing). Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Get') and resource ('detailed information about a specific chapter'), making the purpose unambiguous. It doesn't explicitly differentiate from siblings like 'list_chapters' or 'gql_chapter', but the focus on a single chapter by ID provides implicit 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 'list_chapters' (for multiple chapters) or 'gql_chapter' (which appears to be a GraphQL equivalent). 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 indicates this is a read operation ('Get detailed information'), but doesn't mention authentication requirements, rate limits, error conditions, or what 'detailed information' includes. 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, focused sentence that efficiently communicates the core functionality without unnecessary words. It's appropriately sized for a simple lookup tool and front-loads the essential 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 simple read operation with one well-documented parameter and no output schema, the description is minimally adequate. However, it lacks information about return values, error handling, and authentication needs that would be helpful given the absence of annotations. It's complete enough to understand the basic purpose but leaves operational details unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'coupon_id' well-documented in the schema as an integer >0. The description adds minimal value beyond the schema by mentioning 'by ID', which is already implied. This meets the baseline score when schema coverage is high.
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 ('Get detailed information') and target resource ('about a specific coupon by ID'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'list_coupons' or 'get_promotion_by_coupon', but the specificity of retrieving a single coupon by ID is reasonably 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 like 'list_coupons' for multiple coupons or 'get_promotion_by_coupon' for related data. It states what it does but offers no context about appropriate use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states this is a read operation ('Get'), but doesn't disclose authentication requirements, rate limits, error behavior, or what 'detailed information' includes. 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 that immediately communicates the core purpose without any wasted words. It's perfectly front-loaded with the essential information and achieves maximum clarity with minimal text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool with good schema coverage but no annotations or output schema, the description is minimally adequate. It states what the tool does but lacks important context about return format, error conditions, and relationship to sibling tools. The absence of output schema means the description should ideally hint at what 'detailed information' includes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'id' parameter. The description adds no additional semantic context about the ID parameter beyond what's in the schema. The baseline score of 3 reflects adequate but minimal value addition when the schema does all the 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 action ('Get detailed information') and resource ('about a specific enrollment by ID'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'list_enrollments' or 'get_bundle', but the specificity of retrieving by ID provides some implicit 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 like 'list_enrollments' or 'get_bundle'. It doesn't mention prerequisites, error conditions, or any context about what constitutes a valid enrollment ID beyond the schema's numeric constraint.
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 retrieves 'detailed information,' implying a read operation, but doesn't specify if it requires authentication, rate limits, error conditions, or what 'detailed' entails (e.g., nested objects, permissions). This leaves significant gaps 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.
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 action ('Get detailed information') without any wasted words. It's appropriately sized for a simple retrieval 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?
Given the tool's apparent simplicity (one parameter, no output schema, no annotations), the description is minimally adequate but incomplete. It lacks details on behavioral aspects like authentication or output format, which are crucial for effective use, especially with no output schema to clarify returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'group_id' fully documented in the schema. The description adds no additional meaning beyond implying retrieval by ID, which is already clear from the schema. This meets the baseline for high 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 verb ('Get') and resource ('detailed information about a specific group'), making the purpose evident. However, it doesn't differentiate from sibling tools like 'get_user' or 'gql_group', which likely serve similar retrieval functions for different entities, so it misses 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. It doesn't mention siblings like 'list_groups' for broader queries or 'gql_group' for potentially different data formats, 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 full burden for behavioral disclosure. It states this is a read operation ('Get'), but doesn't mention authentication requirements, rate limits, error conditions, or what 'detailed information' includes. 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, efficient sentence that front-loads the core purpose without unnecessary words. Every word earns its place, making it easy to parse while conveying the essential 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 simple read operation with one well-documented parameter and no output schema, the description is minimally adequate. However, it lacks context about authentication, error handling, or what constitutes 'detailed information,' which would be helpful given the absence of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'order_id' parameter. The description adds no additional parameter semantics beyond what's in the schema (type, constraints, description). This meets the baseline expectation when schema coverage is complete.
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 ('Get') and resource ('detailed information about a specific order by ID'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_orders' or 'get_course', which would be helpful for agent 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 like 'list_orders' (for browsing) or other 'get_' tools for different resources. It mentions the 'by ID' requirement but doesn't explain how to obtain that ID or when this specific 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?
No annotations are provided, so the description carries full burden. It states it's a lookup operation, implying read-only behavior, but doesn't disclose error handling (e.g., invalid codes), permissions required, rate limits, or response format. For a tool with no annotations, 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 waste. It's front-loaded with the core purpose and appropriately sized for a simple lookup 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?
Given the tool's low complexity (single parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks behavioral context and usage guidance, making it incomplete for optimal agent use without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'coupon_code' fully documented in the schema. The description adds no additional parameter details beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate since the schema does the heavy lifting.
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 ('Look up') and resource ('a promotion'), specifying it's done 'by coupon code'. It distinguishes from generic 'get_promotion' by focusing on coupon-based lookup, though it doesn't explicitly contrast with other promotion-related tools like 'list_promotions' or 'get_promotion' (if that exists for other identifiers).
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. Sibling tools include 'get_promotion' (possibly for other lookup methods) and 'list_promotions', but the description doesn't mention these or specify prerequisites like needing a valid coupon code. Usage is implied only by the tool's name and description.
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 read operation ('Get'), implying safety, but doesn't mention permissions required, error handling, rate limits, or what happens if the ID doesn't exist. This leaves significant gaps for a tool that retrieves 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 highly efficient and easy to parse. It's front-loaded with the core action and resource.
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 read tool with one parameter and no output schema, the description is minimally adequate but lacks depth. It doesn't explain return values, error cases, or behavioral nuances, which could be important given the absence of annotations. However, the straightforward nature of the tool keeps it from being severely incomplete.
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 parameter 'script_id' in the schema. Since schema description coverage is 100%, the schema already documents this parameter adequately. The description adds minimal value beyond what the schema provides, meeting the baseline for high 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 ('Get') and resource ('a specific site script by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_site_scripts' or 'create_site_script' beyond the specificity of retrieving a single item by ID.
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 'list_site_scripts' for multiple scripts or 'create_site_script' for creation. It lacks context about prerequisites, such as needing an existing script ID, 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 this is a read operation ('Returns'), implying it's non-destructive, but doesn't cover aspects like authentication requirements, error handling, rate limits, or response format. For a 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 that front-loads the core functionality: 'Returns a User by their global ID (gid) (GraphQL).' There is no wasted verbiage or redundancy, 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.
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 (one parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks behavioral context and usage guidelines. For a read-only tool, this is passable but leaves room for improvement in guiding the agent 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 description coverage is 100%, with the single parameter 'id' documented as 'The user's global ID (gid).' The description adds no additional parameter details beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate.
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: 'Returns a User by their global ID (gid) (GraphQL).' It specifies the verb ('Returns'), resource ('User'), and key identifier ('global ID'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_user' or 'gql_user_by_email', which slightly reduces 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 sibling tools such as 'get_user' (which might use a different API) or 'gql_user_by_email' (which uses email instead of global ID), leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 ('List enrollments') but doesn't describe key behaviors: it doesn't mention pagination (though implied by parameters), rate limits, authentication requirements, error handling, or the format of returned data. 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 zero wasted words. It's front-loaded with the core purpose ('List enrollments for a specific bundle'), making it easy to parse quickly. Every word earns its place, and there's no 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 moderate complexity (a filtered list operation with pagination), no annotations, and no output schema, the description is minimally adequate but incomplete. It covers the basic purpose but lacks behavioral details (e.g., pagination behavior, data format) and usage context. The high schema coverage helps, but for a tool with no output schema, more description of return values would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for 'bundle_id', 'page', and 'limit'. The description adds no additional parameter semantics beyond what the schema provides, such as explaining what a 'bundle' is or how pagination works. However, with high schema coverage, the baseline score of 3 is appropriate as the schema handles the heavy lifting.
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 'List enrollments for a specific bundle' clearly states the verb ('List') and resource ('enrollments'), with the scope ('for a specific bundle') distinguishing it from generic enrollment listing tools. However, it doesn't explicitly differentiate from sibling tools like 'list_enrollments' or 'get_enrollment', which might list all enrollments or get a single enrollment respectively, though the bundle-specific focus 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_enrollments' (which might list all enrollments without bundle filtering) or 'get_enrollment' (which retrieves a single enrollment), nor does it specify prerequisites such as needing a valid bundle ID. Usage is implied by the name but not explicitly 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 for behavioral disclosure. 'List course categories' implies a read-only operation but doesn't specify pagination behavior (implied by parameters), authentication requirements, rate limits, or what happens when no categories exist. For a tool with zero annotation coverage, this is insufficient 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, efficient sentence with zero wasted words. It's appropriately sized for a simple list operation and front-loads the essential information immediately.
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 list tool with 100% schema coverage but no annotations or output schema, the description is minimally adequate. It identifies the resource but lacks behavioral context (pagination, auth, error cases) that would be helpful given the absence of structured metadata. The completeness is borderline acceptable 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?
Schema description coverage is 100%, so parameters 'page' and 'limit' are fully documented in the schema. The description adds no additional parameter semantics beyond what the schema already provides, which meets the baseline expectation when schema does the heavy lifting.
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 'List course categories' clearly states the verb ('List') and resource ('course categories'), making the purpose immediately understandable. However, it doesn't differentiate from similar sibling tools like 'get_category' (singular retrieval) or 'gql_category' (GraphQL alternative), 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 provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_category' (retrieves a single category) and 'gql_category' (GraphQL-based query), the agent receives no help in choosing between list vs. get operations or REST vs. GraphQL approaches.
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 'with pagination', which is useful context about the return format, but doesn't describe other important behaviors like whether this is a read-only operation, what authentication is required, rate limits, or what the response structure looks like. For a list 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 perfectly concise - a single sentence that communicates the core functionality and key behavioral trait (pagination) with zero wasted words. It's front-loaded with the essential information and doesn't contain any unnecessary details.
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 list tool with 2 well-documented parameters and no output schema, the description is minimally adequate. It covers the basic purpose and mentions pagination, but lacks important context about authentication requirements, response format, and when to use versus other list tools. The absence of annotations means the description should do more heavy lifting than it does.
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 doesn't add any parameter semantics beyond what's already in the schema, which has 100% coverage with clear descriptions for both 'page' and 'limit'. The baseline score of 3 is appropriate since the schema does the heavy lifting, though the description could have explained the pagination behavior more explicitly.
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 ('List') and resource ('courses on the Thinkific site'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_bundles' or 'list_categories', which would require mentioning it specifically lists courses rather than other entities.
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, when to choose this over other list tools (e.g., 'list_bundles'), or any contextual 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 the full burden of behavioral disclosure. It states the tool lists analysts, implying a read-only operation, but doesn't mention pagination behavior, rate limits, authentication requirements, or error conditions. For a tool with three parameters and no 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 that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse. Every word earns its place, achieving optimal 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 tool's moderate complexity (three parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, usage context, and output format. Without annotations or output schema, the agent must rely on the schema alone for parameter info, leaving gaps in overall understanding.
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 100%, so the schema fully documents all parameters (group_id, page, limit). The description adds no additional parameter semantics beyond what's in the schema, such as explaining what 'analysts' means in context or how pagination works. This meets the baseline for high 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 ('List') and resource ('analysts (managers) for a group'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'list_groups' or 'list_users', which would require a 5. The mention of 'managers' in parentheses adds some specificity but isn't fully distinguishing.
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 valid group ID, or compare it to similar tools like 'get_group' or 'list_users'. Without any usage context, the agent must 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't mention pagination details (implied by parameters), rate limits, authentication requirements, or what the output looks like. For a list 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, clear sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple list operation, making it easy for an agent to parse quickly.
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 list tool with 2 well-documented parameters and no output schema, the description is minimally adequate. However, it lacks context about the resource (e.g., what promotions are), doesn't mention pagination behavior (though implied by parameters), and provides no output details, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters (page and limit) with their types, constraints, and defaults. The description adds no additional parameter information beyond what's in the schema, which is acceptable given the high coverage, resulting in the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('promotions on the Thinkific site'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'get_promotion' (which likely retrieves a single promotion), leaving some ambiguity about when to use one versus 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 like 'get_promotion' or 'list_coupons' (which might overlap with promotions). There's no mention of prerequisites, context, or exclusions, 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 full burden for behavioral disclosure. It states it's a list operation (implying read-only), but doesn't mention pagination behavior, rate limits, authentication requirements, error conditions, or what constitutes 'related' products. For a tool with 3 parameters and 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 that states exactly what the tool does with zero wasted words. It's appropriately sized for a straightforward list operation and gets directly to the point without 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?
For a read-only list tool with good schema coverage but no output schema, the description is minimally adequate. It states the core purpose but lacks important context about what 'related' means, how results are determined, pagination details, and error handling. The absence of annotations and output schema means the description should do more to compensate.
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 'for a given product' which implies the product_id parameter, but doesn't add meaningful context beyond what the 100% schema coverage already provides. The schema descriptions clearly document all three parameters, so the description adds minimal value. This meets the baseline for high 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 ('List') and resource ('related products for a given product'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'list_products' or 'list_category_products', but the specificity of 'related products' provides inherent distinction. This is clear but lacks explicit sibling 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?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when this tool is appropriate compared to other list tools, or any contextual constraints. The agent must infer usage purely from the tool name and parameters.
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 tool retrieves metrics for monitoring and optimization, but lacks details on behavioral traits such as required permissions, rate limits, data freshness, or potential side effects (e.g., the 'reset' parameter's impact). This is a significant gap for a tool with potential performance implications.
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: the first states the purpose, and the second provides usage context. It's front-loaded with key information and avoids unnecessary details, though it could be slightly more structured (e.g., separating purpose from guidelines).
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 (performance metrics with a reset option), no annotations, and no output schema, the description is incomplete. It covers the basic purpose but lacks details on behavioral traits, output format, or error handling, which are crucial for effective use by an AI agent in a monitoring 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 100%, so the schema already documents the single parameter ('reset') with its type and default. The description adds no additional parameter semantics beyond what the schema provides, such as explaining the implications of resetting metrics or typical usage patterns. Baseline 3 is appropriate when the schema handles 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 tool's purpose with specific verbs ('Get performance metrics and statistics') and resources ('API calls, cache hit rates, and tool execution times'). It distinguishes itself from sibling tools by focusing on monitoring and optimization rather than CRUD operations on business entities like users or courses, though it doesn't explicitly name alternatives.
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 context ('Use this to monitor and optimize MCP server performance'), providing a general purpose. However, it doesn't specify when to use this tool versus alternatives (e.g., other monitoring tools or logs) or any prerequisites, leaving some ambiguity for the 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?
No annotations are provided, so the description carries full burden. It mentions fetching counts but doesn't disclose behavioral traits like whether this is a read-only operation, requires authentication, has rate limits, or returns structured data. 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 that front-loads the core purpose ('Get overview information') and specifies key details ('course and user counts'). There is no wasted language, making it easy for an agent to parse quickly.
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 (0 parameters, no output schema), the description is adequate but incomplete. It lacks behavioral context (e.g., read-only nature, response format) and usage guidelines, which are important even for simple tools. Without annotations or output schema, the description should do more to compensate, but it only covers the basic purpose.
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 the schema fully documents the absence of inputs. The description adds no parameter information, which is appropriate here. Baseline is 4 for zero parameters, as no additional semantics are needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get overview information') and resource ('connected Thinkific site'), specifying it fetches 'course and user counts'. It distinguishes from siblings like 'get_course' or 'get_user' by focusing on site-wide overview rather than specific resources. However, it doesn't explicitly differentiate from all siblings (e.g., 'gql_site' might overlap), 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?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for site overview, but doesn't specify scenarios (e.g., initial setup, monitoring) or exclusions (e.g., use 'get_performance_metrics' for detailed analytics). Without such context, the agent must infer usage from the purpose 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 it returns the current authenticated user via GraphQL, which implies a read-only operation, but doesn't clarify authentication requirements, rate limits, error conditions, or what data is included in the response. This is a significant gap for a 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 that front-loads the core functionality ('Returns the current authenticated user') and adds necessary context ('GraphQL') without any fluff. 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.
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 (0 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose but lacks behavioral details like authentication needs or response format, which are important for a tool that likely requires user context. 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?
The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description appropriately doesn't waste space on parameter details, earning a baseline score of 4 for not adding 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 verb ('Returns') and resource ('current authenticated user'), making the purpose specific and understandable. It distinguishes from siblings by specifying it's for the current user rather than a general user lookup, though it doesn't explicitly contrast with tools like 'gql_user' or 'get_user'.
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 'gql_user', 'get_user', or 'gql_user_by_email'. There's no mention of prerequisites, context, or exclusions, leaving the agent to infer usage based on 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 'Returns site information' but doesn't disclose behavioral traits like whether this is a read-only operation, authentication requirements, rate limits, or what specific information is included. The mention of 'GraphQL' hints at the query mechanism but lacks operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core purpose ('Returns site information'), making it easy to parse quickly.
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 is minimally adequate but lacks completeness. It doesn't explain what 'site information' includes, the GraphQL specifics, or how this differs from similar tools, leaving gaps in understanding for an AI agent despite the simple structure.
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 the schema fully documents the lack of inputs. The description doesn't need to add parameter details, and it correctly implies no inputs are required, earning a high baseline score for this dimension.
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 ('Returns') and resource ('site information for the connected Thinkific site'), making the purpose understandable. However, it doesn't differentiate from the sibling tool 'get_site_info', which appears to serve a similar purpose, 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 like 'get_site_info' or other GraphQL siblings. It mentions 'GraphQL' but doesn't explain why to choose this over REST-based tools or when it's appropriate, 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 the full burden of behavioral disclosure. It states 'List instructors' but doesn't mention that it's a read-only operation, requires pagination (implied by schema but not described), or any rate limits or authentication requirements. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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 a single, efficient sentence: 'List instructors on the Thinkific site.' It is front-loaded with the core purpose, has zero wasted words, and appropriately sized for a simple list operation. Every word earns its place without 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 (simple list with pagination), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like read-only nature, authentication needs, or response format. For a tool with 2 parameters and no structured safety hints, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear documentation for 'page' and 'limit' parameters including defaults and constraints. The description adds no additional parameter semantics beyond what the schema provides, such as explaining the pagination model or result ordering. Baseline 3 is appropriate when the schema does the heavy lifting, but no extra value is added.
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 'List instructors on the Thinkific site' clearly states the verb ('List') and resource ('instructors'), specifying what the tool does. It distinguishes itself from sibling tools like 'get_instructor' (singular retrieval) and 'create_instructor'/'delete_instructor'/'update_instructor' (mutations). However, it doesn't explicitly mention pagination or filtering capabilities, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving multiple instructors, contrasting with 'get_instructor' for single retrieval. However, it lacks explicit guidance on when to use this tool versus alternatives like 'list_users' or 'search_users' for broader queries, or prerequisites such as authentication needs. The context is clear but incomplete for optimal agent 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?
No annotations are provided, so the description carries full burden. It mentions filtering behavior ('exact or partial email match'), which is useful. However, it doesn't disclose critical behavioral traits like whether this is a read-only operation, pagination details (implied by parameters but not described), rate limits, authentication requirements, or what the response format looks like. For a search tool with no annotations, 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 appropriately sized and front-loaded with the core purpose in the first sentence. The second sentence adds useful API-specific context without redundancy. Both sentences earn their place by providing essential information efficiently, with zero waste 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?
Given the tool's complexity (search with pagination), lack of annotations, and no output schema, the description is incomplete. It covers the basic purpose and filtering behavior but misses critical details like response format, error handling, pagination behavior beyond parameters, and differentiation from sibling tools. For a tool that returns data without structured output documentation, this leaves too much unspecified for 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 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'email address (or partial email)' for the query parameter, but this is redundant with the schema's description. No additional semantics are provided for 'page' or 'limit.' With high schema coverage, the baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for users by email address' specifies the verb (search), resource (users), and search criteria (email). It distinguishes from generic user retrieval tools like 'get_user' or 'list_users' by focusing on email-based search. However, it doesn't explicitly differentiate from 'gql_user_by_email' which appears to be a sibling tool with similar functionality.
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 context by stating 'The Thinkific API filters users by exact or partial email match,' which suggests when this tool is appropriate. However, it doesn't explicitly state when to use this versus alternatives like 'gql_user_by_email' or 'list_users,' nor does it mention any prerequisites or exclusions. The guidance is present but incomplete.
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 is for finding (implying a read operation) but doesn't mention critical details like authentication requirements, rate limits, error handling, or what happens if no user is found. For a tool with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: the first phrase states the core purpose, followed by a brief mention of optional filters. Every word earns its place with no redundancy or fluff, making it easy for an agent to parse quickly.
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 is minimally adequate. It covers the basic purpose and parameters but lacks details on behavioral aspects like response format, error cases, or authentication. Without annotations or output schema, the agent has incomplete 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 description coverage is 100%, with clear descriptions for all three parameters (id, communityId, userId). The description adds minimal value by mentioning the optional filters, but doesn't provide additional semantics beyond what the schema already documents, such as how filters interact or format specifics. This meets the baseline for high 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 tool's purpose: 'Find a community user by ID (GraphQL).' It specifies the verb ('Find'), resource ('community user'), and method ('GraphQL'), making the intent unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'gql_user' or 'get_user', which likely serve similar purposes, 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 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 mentioning optional filters ('Optionally filter by communityId or userId'), suggesting when to use these parameters. However, it lacks explicit instructions on when to choose this tool over alternatives like 'gql_user' or 'search_users', and doesn't specify prerequisites or exclusions, leaving some ambiguity for the 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 specifies the valid reaction types but does not mention whether this is a mutation (likely, as it adds a reaction), permission requirements, rate limits, or what happens on duplicate reactions. This leaves significant gaps for a tool that likely 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 that front-loads the core action and lists all valid reactions without unnecessary words. Every part of the description serves a clear purpose, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description is incomplete for a mutation tool. It covers the action and valid reactions but lacks details on behavioral traits (e.g., side effects, error handling) and return values, which are critical for proper 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?
The schema description coverage is 100%, with clear descriptions for both parameters, including an enum for 'reaction'. The description adds value by listing all valid reaction types explicitly, but it does not provide additional context beyond what the schema already documents, such as format examples for 'postId'.
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 ('React to a post') and resource ('post') with the method ('with an emoji reaction'), and it distinguishes itself from sibling tools like 'gql_create_post', 'gql_reply_to_post', or 'gql_update_post' by focusing on reactions rather than creation, replies, or updates.
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 when to react versus reply or update a post. It lacks context on prerequisites (e.g., needing post access) or exclusions, leaving usage unclear 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. It states the action ('List coupons') but doesn't disclose behavioral traits like pagination behavior (implied by 'page' and 'limit' parameters but not explained), rate limits, authentication needs, or what the output looks like. 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 two concise sentences with zero waste. The first sentence states the purpose, and the second adds essential context about the coupon-promotion relationship. It's front-loaded and efficiently structured, making it 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 moderate complexity (3 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the purpose and resource relationship but lacks details on behavior, output format, and usage guidelines. With no output schema, the description should ideally hint at return values, but it doesn't, leaving gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for all parameters (e.g., 'Promotion ID (use list_promotions to find IDs)'). The description adds minimal value beyond the schema, as it doesn't explain parameter interactions or provide additional context. With high schema coverage, the baseline is 3, and the description doesn't significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('coupons for a promotion'), and specifies the relationship to promotions ('Thinkific coupons belong to promotions'). It distinguishes from siblings like 'get_coupon' (singular) and 'bulk_create_coupons', but doesn't explicitly differentiate from other list tools like 'list_promotions'. The purpose is specific and actionable.
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 when needing coupons for a specific promotion, and the parameter description for 'promotion_id' references 'list_promotions' to find IDs, providing some contextual guidance. However, it lacks explicit when-to-use vs. alternatives (e.g., 'get_coupon' for a single coupon) or prerequisites. Usage is implied but not fully articulated.
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 it mentions the 'promotion_id' requirement, it doesn't describe what happens when a coupon is created (e.g., whether it's immediately active, what permissions are needed, or what the response looks like). 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 extremely concise with just two sentences that both earn their place. The first sentence states the purpose, and the second provides crucial usage guidance. There's zero waste 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, what happens on success/failure, or important behavioral aspects like whether duplicate codes are allowed. Given the complexity of creating a coupon, more context would be 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?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds minimal value by reinforcing the 'promotion_id' requirement but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline for high 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 ('Create a new coupon/discount code') and resource ('coupon/discount code'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'bulk_create_coupons' or 'update_coupon' beyond the 'create' verb, which is why it doesn't reach 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('Requires a promotion_id — use list_promotions first to get one'), which helps the agent understand prerequisites. However, it doesn't explicitly state when NOT to use it or mention alternatives like 'bulk_create_coupons' for multiple coupons, so it falls short of a perfect score.
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 promotions. It doesn't disclose behavioral traits like required permissions, whether promotions are immediately active, what happens on creation failure, rate limits, or response format. 'Create' implies mutation but lacks detail about the operation'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 perfectly concise with two sentences that each earn their place: the first states the core purpose, the second provides workflow guidance. No wasted words, front-loaded with the essential 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 mutation tool with no annotations and no output schema, the description is minimally adequate. It covers the basic purpose and workflow relationship but lacks details about behavioral aspects, error conditions, or what the tool returns. The 100% schema coverage helps, but more behavioral context would be needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema, establishing the baseline score of 3 where schema does the heavy lifting.
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: 'Create a new promotion (discount)' with the specific verb 'Create' and resource 'promotion'. It distinguishes from siblings like 'create_coupon' by explaining promotions hold coupon codes, but doesn't explicitly contrast with 'update_promotion' or 'delete_promotion'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about workflow: 'Create a promotion first, then create coupons under it.' This gives guidance on when to use this tool in relation to 'create_coupon', but doesn't explicitly mention when NOT to use it or alternatives like 'update_promotion'.
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:

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

Score Badge

Copy to your README.md:

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

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/ackbarguppi-ai/thinkific-mcp'

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