brilliant-directories-mcp

Official

by brilliantdirectories

Overview Schema Related Servers Score Discussions(1)

JavaScript

Remote

Server Quality Checklist

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

Latest release: v6.58.592
Disambiguation5/5
Each tool targets a specific resource and action (create, read, update, delete, list). Resources like TopCategory, SubCategory, MemberSubCategoryLink are clearly distinguished. No two tools appear to do the same thing.
Naming Consistency5/5
Every tool follows a consistent verb_noun pattern (e.g., createClick, deleteClick, getClick, listClicks). Even helper tools like getBrandKit, verifyToken are named predictably. No mixed conventions.
Tool Count2/5
170 tools is excessive for a single MCP server. While each entity type has full CRUD, the sheer number makes the surface overwhelming and hard to navigate. Most servers with similar scope have 20-40 tools.
Completeness4/5
CRUD operations are present for nearly all entity types. Minor gaps exist (e.g., no createUserMeta, but meta is handled via updateUser/updateWebPage redirects). The set covers the full domain of BD site management.
Average 4.7/5 across 165 of 170 tools scored. Lowest: 3.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1145 commits in the last 12 weeks
- Last stable release on August 14, 2026
- 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.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
View related servers

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds key behaviors: PATCH semantics ('Fields omitted are untouched'), the warning about state_filename breaking URLs, and the 'corrections only' nature. These details help the agent understand side effects and safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose. It uses clear formatting with bold and warning. The only redundancy is 'Update a state (corrections only) - Update a state row.' Overall, it is well-structured and free of unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, annotations, and no output schema, the description covers purpose, PATCH semantics, required field, and a critical warning. It misses guidance on usage relative to siblings and detailed field meanings, but for a PATCH update tool, it is reasonably complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds PATCH semantics (fields omitted untouched) and warns about state_filename, which adds value beyond the schema. However, with only 33% schema description coverage, other parameters (state_sn, state_ln, country_sn) lack explanation in the description. The baseline is 3 due to low coverage, and the description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a state (corrections only) - Update a state row.' This specifies the verb (update) and resource (state), and adds 'corrections only' to distinguish from general updates. The purpose is unambiguous and differentiates from sibling update* tools for other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Read-mostly - use for corrections' and warns about state_filename renaming, implying when to use (corrections) and what to avoid (renaming without redirects). However, it does not explicitly state when not to use this tool or suggest alternatives, leaving room for improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds the return format and parameter requirement, providing additional context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences, front-loading the purpose. Uses bold for emphasis on requirements, making it scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description covers the essential aspects: purpose, required input, and return format. No missing information for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It mentions 'country_id' is required and a path parameter but does not explain what it represents, any constraints, or its format. Minimal added value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single country by ID, using specific verbs ('Get', 'Fetch') and resource ('country row'). It distinguishes from sibling tools like listCountries by indicating it fetches one row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the required parameter and read-only nature but does not explicitly state when to use this tool over alternatives like listCountries or updateCountry. Usage context is implied but not formally outlined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description reveals appending photos and silent failures, but contradicts annotations: idempotentHint=true is false because appending photos is not idempotent (duplicates on retry). This is a major contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bolded terms, but somewhat lengthy. Every sentence adds value, but could be more concise for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format, async photo processing, verification via listMultiImagePostPhotos, silent failure conditions, and references to related rules. Adequate for a complex multi-faceted tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 70% schema coverage, description adds critical meaning: post_image appends and requires landscape, auto_image_import fetches externally, group_status enum meanings, group_filename slug behavior, and _clear_fields mechanism. Fully compensates for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific action verb 'Update', identifies resource 'album group/portfoliogroup', and distinguishes from siblings like createMultiImagePost and deleteMultiImagePost. It also clarifies scope: 'by ID' and 'fields omitted are untouched'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' section lists editing metadata or appending photos, and notes alternative tool updateMultiImagePostPhoto for editing existing photos. 'See also' lists related tools, providing clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context (writes live data, external replication use case) beyond annotations. However, it contradicts the schema by suggesting click_type has limited values (link/phone/email) while schema says free-form, reducing accuracy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, front-loaded purpose, and no wasted sentences. It efficiently conveys usage, requirements, and parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 required params and no output schema, the description covers the use case, parameter interactions, and alternates. Missing details on response or side effects, but adequate for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema description coverage, the description attempts to add meaning for all 5 parameters, but for click_type and click_from it provides restrictive interpretations that conflict with the schema's free-form nature. It adds some value but with inaccuracies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a click record and writes live data. It distinguishes from the sibling 'updateClick' by mentioning it in the 'See also' section, providing differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (replicating external click events) and when not to (BD auto-records). It also lists required parameters and references an alternative tool (updateClick).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds return format and not-found behavior ('Empty or HTTP 404') beyond annotations that already declare readOnlyHint=true and idempotentHint=true. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, structured with clear sections (Use when, Required, See also, Returns). No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations and detailed schema, description completes the picture by specifying return format. Lacks explanation of output schema (none provided) but is adequate for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 67% of parameters in detail. Description only reinforces required field_id, adding no new semantic value for the optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single form field' and contrasts with sibling 'listFormFields' for enumeration. Verb+resource is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: one field by ID' and lists required parameter. References sibling tool for alternatives. Lacks explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent. Description adds response format and 404 behavior, providing extra context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sections: purpose, usage condition, required param, and return format. No fluff, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-record retrieval with one param and no output schema, description covers purpose, usage, required input, and return structure (including error case). Could include an example but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only required param is match_id; description states it's required and derived from listLeadMatches but does not describe its meaning beyond that. Schema has 0% description coverage, so description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'get' and resource 'lead match record', and distinguishes from sibling listLeadMatches by specifying single record retrieval. Title is null but name itself communicates purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when you have a specific match_id' and references listLeadMatches for context. Implicitly tells when not to use (when no ID). Could explicitly state alternatives but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by stating 'Fields omitted are untouched' (aligning with idempotentHint) and 'Writes live data'. It also describes the return format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly structured with clear sections, front-loaded main sentence, and no unnecessary words. Every sentence serves a purpose (use case, required param, enums, see also, returns).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and no output schema, the description covers purpose, usage, return format, and sibling distinctions. It lacks detailed explanation of _clear_fields but the schema covers that. Overall complete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats enum values already in schema and mentions the required photo_id, but does not explain the meaning of photo_id or type beyond the enum. Schema description coverage is 33%, and the description partially compensates by restating enums, but misses adding new semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing user photo record by ID. It distinguishes from sibling tools by explicitly referring to createUserPhoto and deleteUserPhoto, clarifying its role as an update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section provides a clear, specific scenario: changing a photo's type slot. It also references create and delete alternatives, but does not explicitly exclude other use cases or compare with other update tools like updateUser.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint=false and destructiveHint=false. Description adds 'Writes live data' but no further behavioral details beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, front-loaded purpose, and no fluff. Minor redundancy in opening sentence but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, prerequisites, parameter details, and alternative. Lacks output info but acceptable without output schema. Sufficient for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), but description explains each parameter: user_id as member, type with enum values, and file requirement (must exist in storage), adding significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create'), resource ('user photo'), and distinguishes from siblings by specifying 'Create a new userphoto record' and referencing 'updateUserPhoto' for modifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('attaching a new photo record to a member'), prerequisite (image must exist in site storage), and replaces 'See also' with alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds important context about the lean-by-default keep-list, the include flags to expand the response, and that it returns 404 when not found. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, keep-list, flag explanations, usage guidance, required field, see also, return format. It front-loads the main purpose. While it is somewhat lengthy, every sentence adds value and the structure is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description includes the return format and 404 behavior. Parameters are well-explained through both schema and description. The keep-list and flags are thoroughly documented. Sibling tools are referenced. It is complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86% (high), so baseline is 3. The description provides high-level context for the include_* flags by explaining the lean-by-default strategy, but the schema already fully describes each parameter. The description does not add significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single post - Fetch a single post record. Read-only.' It specifies the resource (post) and action (fetch/get), and distinguishes from the sibling tool listSingleImagePosts by stating 'For enumeration or keyword search use listSingleImagePosts'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Use when: fetching one post by post_id. For enumeration or keyword search use listSingleImagePosts'. Also provides a 'See also' reference to the sibling tool. This clearly tells when to use and what alternative to use for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: 'Writes live data' and 'Fields omitted are untouched'. Annotations already indicate not read-only, not destructive, idempotent, and open world, but description reinforces 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?
Concise and well-structured with clear sections (purpose, usage, required, see also, returns). Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, covers required param, return format, and field behavior. Lacks detail on specific optional params but overall adequate given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 20% schema coverage, only _clear_fields is documented in schema. Description only mentions required click_id, not the meaning of click_type, click_name, click_url. Fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a click record' with a specific verb and resource, and distinguishes from siblings by mentioning createClick and deleteClick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('correcting click metadata') and notes rarity, with 'See also' referencing alternatives. Provides clear guidance on use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that omitted fields are untouched and that writes affect live data, consistent with the idempotentHint and openWorldHint annotations. It also details the behavior of `_clear_fields`, which is critical for understanding updates. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose, including lengthy contextual digressions about member classification and sub-sub-categories that are tangential to the tool's core purpose. The first paragraph is concise, but the extraneous information could be trimmed without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters and no output schema, the description provides a detailed return format and a rule for clearing fields. It also explains the data model context, aiding understanding of when this tool applies. Minor gaps: no mention of error handling or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema description coverage, the description compensates by explaining all updatable parameters (`avg_price`, `specialty`, `num_completed`, `date`) and providing a thorough explanation of `_clear_fields`. It adds meaningful context beyond the schema's basic type definitions.
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 opens with 'Update a user-service relationship - Update a Member ↔ Sub Category link by `rel_id`', clearly stating the verb (update) and resource (a specific link). It explicitly distinguishes from sibling tools like `createMemberSubCategoryLink` and `deleteMemberSubCategoryLink`, which are listed under 'See also'.
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 usage context with 'Use when: adjusting per-link metadata' and lists the exact updatable fields. It also points to alternative tools for creating and deleting. However, it does not explicitly state when not to use this tool, though the context is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description confirms writes ('Writes live data') but does not disclose authorization needs, side effects, or return value. With annotations providing some safety profile, the description provides moderate additional context but lacks completeness.
Agents need to know what a tool does to the world before 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 about 10 lines, front-loaded with purpose, then covers usage, required fields, enums, parameter interactions, and see-also. Every sentence is necessary and contributes to understanding, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 params, 5 required, no output schema), the description covers usage conditions, parameter interactions, enums, and provides a sibling reference. However, it omits return value and error conditions, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 44% (4/9 params have descriptions). The description adds valuable semantics for key parameters: explains `menu_id` as parent menu container, `master_id` as 0 for top-level, `menu_order` as position, and `menu_target` enums. It compensates significantly for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a menu item - Create a new menuitem record. Writes live data.' It clearly identifies the verb (create) and resource (menu item), and distinguishes from siblings like 'createMenu' and 'updateMenuItem'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use: 'adding a nav link to an existing menu. Parent `menu_id` must exist. For nested items pass `master_id=<parent menu_item_id>`; for top-level pass `0`.' It also references 'updateMenuItem' for modifications, offering clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only, non-destructive, non-idempotent, open world. Description adds that it writes live data, does not import external URLs, and parent album's auto_image_import does not cascade. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is verbose with nested formatting and bullet points. Front-loaded with purpose but contains lengthy explanations that could be more concise. Still structured and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameters, limitations, and alternatives. No output schema, so return value is not expected. Provides sufficient context for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (25%), but description explains user_id and group_id as required, group_id source, and original_image_url constraints (public, verbatim). Title not explicitly described but inferable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it creates an album photo record, specifying 'album photo' and 'portfoliophoto record'. It distinguishes from sibling createMultiImagePost by clarifying it adds one photo to an existing album.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' condition, prerequisite of parent album existence, and explicit 'Do NOT use' scenario for external URLs. Provides alternatives: createMultiImagePost for bulk import with auto_image_import, updateMultiImagePostPhoto for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it writes live data, is site-wide and all-or-nothing, and affects global unsubscribe list. Annotations are minimal (readOnlyHint false, destructiveHint false) but the description adds important behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet-like sections (Use when, Required, Enums, See also). Around 120 words, no unnecessary fluff, though it repeats 'email is the only meaningful input' twice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage, scope, and alternatives well, but fails to mention what the tool returns (no output schema). For a create tool, the agent might expect info on the created record or confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds extra meaning: emphasizes that email is the only meaningful input, explains the scope of unsubscribe, and clarifies the definitive enum values (0,1). This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates a new unsubscribe record for an email, with specific verb 'create' and resource 'unsubscribe'. Differentiates from sibling tools like updateUnsubscribe and deleteUnsubscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('programmatically opting a member out of emails') and provides alternative ('See also: updateUnsubscribe') with clear context that BD also does this automatically on click.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses permanence, no undo via API, no soft delete, and records not recoverable. Also specifies the return format. Annotations already provide destructiveHint=true and readOnlyHint=false, and the description adds crucial context beyond them. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bold key points. Every sentence adds value, front-loads the essential action, and avoids fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage context, behavior, and return value. Warns about bulk use. Could mention potential cascading effects on references, but for a simple deletion it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one required integer parameter with 0% description coverage. Description explicitly states 'Required: menu_item_id' and confirms it identifies the record by ID. Adds some meaning but no format, constraints, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a menu item permanently by ID. It distinguishes from sibling updateMenuItem (modify without removing) and deleteMenu (deletes a menu), making the specific verb+resource+scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: removing a single menu entry' and provides a 'See also' reference to updateMenuItem. Warns about destructive nature and to confirm intent before bulk use. Lacks explicit alternatives for bulk or multiple items, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: the return format (status and message array) and the behavior when not found (empty or HTTP 404). This goes beyond what annotations provide, though it doesn't elaborate on other traits like authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using only four short lines. It is front-loaded with the core action and uses clear section headers (Use when, Required, See also, Returns). Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, read-only, fixed return structure). The description covers purpose, usage context, required parameter, related sibling, and return format including error scenario. With no output schema, the description compensates fully. It is complete for the given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only repeats 'Required: form_id.' without adding meaning about what form_id is, any format constraints, or examples. The schema already defines type and required status, so the description adds negligible value for this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get a single form - Fetch a single form record. Read-only.' This clearly identifies the verb (get) and resource (single form), and distinguishes from siblings like listForms by specifying scope. The read-only annotation reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use when: fetching one form's metadata.' and references sibling 'listForms (enumerate many).' This tells the agent when to use this tool and when to use an alternative, satisfying the usage guidelines dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare read-only. The description reinforces this ('Read-only') and adds return format details ('{ status: "success", message: [{...record}] }'). No contradictions; adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, but contains extensive tangential background on member classification and sub-sub-categories that is not directly relevant to using this tool. This extra content reduces conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a simple parameter set and no output schema, the description provides return format, use cases, and related concepts. The extra background adds completeness for understanding context, though not strictly necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by naming the required parameter ('rel_id'), noting it is required, and explaining its role ('by rel_id'). Since only one simple parameter, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Get'/'Fetch'), the resource ('Member ↔ Sub Category link'), and the key parameter ('rel_id'). It distinguishes from the sibling 'listMemberSubCategoryLinks' by noting the scope difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly specifies when to use ('when you have a rel_id'), rarity, and provides an explicit alternative ('listMemberSubCategoryLinks' for enumeration/filtering). Also notes common workflow patterns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it is 'Read-only' and provides detailed return format: a bare array (not wrapped in status/message) with specific fields like key, label, required, type, etc. It also includes a 'Silent-fallback warning' about potential misleading responses. This adds context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but well-structured with clear sections. It front-loads the purpose and then provides usage guidelines, parameter requirement, return format, and warnings. It is slightly verbose but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description provides comprehensive context: the purpose, when to use, required parameter, detailed return structure, and a critical warning about silent fallback. It also notes a nuance about categorization. This is sufficient for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema). The description states 'Required: `form_name`' and clarifies that form_name must match a real post-type form. However, it does not explain what form_name represents (e.g., the form's name or identifier), leaving some ambiguity. It adds minimum value beyond the schema requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get album group field definitions - Fetch field definitions for a multi-image post type form. Read-only.' It uses a specific verb (fetch) and resource (field definitions for multi-image post type form) and distinguishes from sibling 'getSingleImagePostFields' by mentioning the 'users_portfolio_groups' resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: discovering per-post-type custom fields for multi-image posts - same pattern as `getSingleImagePostFields` but for the `users_portfolio_groups` resource.' It also warns that if 'form_name' does not match a real post-type form, the API may return a generic field list without error, and advises verifying the form_name exists in 'listPostTypes' before trusting the response.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive. The description adds that it only returns custom sidebars, not master defaults, providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: purpose, required parameter, behavioral note, and return format. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers the key aspects: what it does, required param, behavior, and return format. Could mention error handling but overall complete for a simple getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for sidebar_id (0% coverage), but the description explains it is required and identifies the sidebar, adding necessary meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single custom sidebar by ID, distinguishing it from siblings like listSidebars.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies the required parameter and clarifies that only custom sidebars are returned, with a note about master defaults. Does not explicitly exclude alternatives but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly states read-only and provides return format structure ({ status, message }), adding value beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: three sentences serving distinct purposes (what, required param, return). Information is front-loaded and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all essential aspects for a simple get tool: action, input, output format. Lacks error handling or behavior when record not found, but sufficient for typical 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?
With 0% schema coverage, description partially compensates by stating location_id is required and is a path parameter, and noting the primary key spelling. Lacks detailed semantic guidance on valid values or source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (get/fetch), resource (state/province), and identifier (by location_id). Distinguishes from sibling tools like listStates (multiple) and getCity/getCountry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for fetching a single state row by location_id and specifies the required parameter. Does not explicitly list when not to use, but the purpose is self-explanatory given siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, destructive=false, idempotent=true. Description adds return format and not-found handling, enhancing 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?
Very concise, front-loaded, and well-structured with clear sections. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, the description covers purpose, usage, required param, return format, and error case. Fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description only repeats 'Required: id' from schema. No additional meaning about the parameter beyond its name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get a single tag' and 'Fetch a single tag record.' Distinguishes from sibling listTags by mentioning it enumerates many tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: fetching one tag by ID' and 'Required: id.' Also provides 'See also: listTags' for alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld. Description adds 'Read-only' and return format including empty/404 behavior. Provides extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with clear sections: Use when, Required, See also, Returns. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description covers purpose, usage, alternatives, and return behavior. No gaps given the single parameter and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, description only mentions required photo_id without additional semantic context (e.g., format, source). Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches a single user photo record by photo_id. Distinguishes from sibling listUserPhotos by specifying 'single' vs 'enumerate many'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('fetching one photo record by photo_id') and points to alternative listUserPhotos for enumerating many.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by stating it is a 'read-only source-of-truth' for search URLs, that the table is system-critical, and that create/delete are omitted—context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose first, then usage, then filter details, then return columns, then system notes. Efficient with no fluff, though slightly technical in places. Minor room for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use, parameter filter details, return columns (despite no output schema), and system-critical context. No gaps for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description highlights key filters (state_ln, state_sn, state_filename, country_sn) but adds minimal new meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists states/provinces/regions as paginated enumeration, and distinguishes from siblings by specifying it is country-agnostic and holds first-admin-level divisions for all active countries, making it unique among list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: resolving a state/province name to its state_filename slug before constructing a search-result URL.' Also mentions that create/delete are omitted and to use updateState only for corrections, guiding against improper use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and not destructive. The description adds valuable behavioral context: PATCH semantics, the role of `_clear_fields`, and that the primary action is toggling `active`. This goes beyond the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two clear sentences and one bullet. Every sentence adds value, and critical information (purpose, PATCH semantics, required param) is at the beginning. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and a simple update operation, the description covers the essential aspects: main use case, required parameter, PATCH behavior, and the `_clear_fields` feature. It could optionally mention what happens if the country doesn't exist or permissions needed, but the annotations and schema already imply some flexibility. Overall, it's adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (40%), but the description compensates by explaining the PATCH semantics and the special `_clear_fields` parameter in detail (including an example and reference to a rule). It also calls out `country_id` as required and mentions `active` toggling. The meaning of `country_code` and `country_name` is left to the schema, which already describes `country_code`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Update a country record' with a specific focus on 'toggling `active` to enable/disable a country on the site'. The title 'Update a country (corrections / active toggle)' further clarifies the primary use cases. This distinguishes it from sibling update tools targeting 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides key usage guidance: it mentions 'Read-mostly - primary use is toggling `active`' and that 'Fields omitted are untouched (PATCH semantics - only send what you want to change)'. It also highlights the required parameter `country_id`. While it doesn't explicitly specify when not to use the tool or name alternatives, the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds 'Fields omitted are untouched' for partial update behavior and 'Writes live data' for immediacy, providing context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly structured with clear sections: purpose, use-when, required, enums, see-also, returns. Every sentence is informative and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters and no output schema, the description provides a solid overview, enum details, and return format. It references external rules but otherwise covers key aspects. Could be slightly more detailed on return behavior beyond the message.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%. Description explains enums for signature, notemplate, category_id, and unsubscribe_link, and describes _clear_fields. However, parameters like email_type, website, email_from, priority, content_type lack elaboration in description, so it partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an email template' and explains the action (update by ID), resource (email template), and key behavior (fields omitted are untouched, writes live data). It distinguishes from siblings like createEmailTemplate and deleteEmailTemplate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' section lists scenarios (editing subject, body, wrapper mode, etc.) and contrasts with create/delete tools via 'See also:' references. Required parameter specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds 'Writes live data' and 'Fields omitted are untouched', which are useful behavioral insights beyond what annotations offer. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with 3 sentences plus bullet points for 'Use when', 'Required', 'See also', and 'Returns'. Information is front-loaded and every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description includes the return format. It covers the required parameter, partial update behavior, and usage context. However, it does not mention error handling or rate limits, which would be helpful 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 50% (3 of 6 parameters have descriptions). The description adds the important note that 'Fields omitted are untouched' and highlights the required smart_list_id. However, it does not add detailed semantics for the remaining parameters beyond what the schema already provides, so it only partially compensates.
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 starts with 'Update a smart list' and clearly states it updates an existing record by ID. It distinguishes from siblings by explicitly mentioning createSmartList and deleteSmartList in the 'See also' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use when' section that states 'editing the filter criteria or schedule on a saved list', and a 'See also' section that names createSmartList (add new) and deleteSmartList (remove permanently), providing clear context for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context beyond annotations: 'Fields omitted are untouched' clarifies idempotent behavior, 'Writes live data' aligns with readOnlyHint=false, and return format is detailed. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with 'Use when:', 'Required:', 'See also:', and 'Returns:' sections. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage guidance, required fields, behavioral traits, return format, and special parameter details. Lacks explanation of group_tag_name, but overall sufficient for a 3-parameter tool with annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 33% schema coverage, but description compensates by explaining the _clear_fields mechanism and partial update behavior. However, group_tag_name parameter lacks any description in schema or text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'tag group', and distinguishes from siblings like createTagGroup and deleteTagGroup by mentioning them in 'See also'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when:' guidance (renaming a tag group) and lists required parameter 'id'. 'See also' mentions alternatives. However, it could be more explicit about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent). Description adds practical return format and rate-limit context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with clear sections (use-when, returns). Minor repetition but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully covers purpose, usage, behavior, and return format. Complete for a zero-parameter tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100%, baseline 4. Description doesn't need additional parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it verifies API key validity and checks rate limit status. Distinct from all sibling CRUD tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends use at session start to save rate-limit budget. Lacks 'don't use when' but sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations (readOnlyHint=false, etc.), the description adds extensive behavioral context: 'Writes live data', detailed 'Wrapper-enforced refusals', and 'Agent pre-checks'. This goes well beyond annotations to fully disclose validation rules and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed and well-organized with sections, but it is lengthy due to extensive references and examples. While structured, it could be more concise for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 18 parameters, no output schema, and complex enums, the description is highly complete. It covers required fields, validation rules, real-world examples, and references to rules. Agent pre-checks and wrapper-enforced refusals ensure agents have full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 94% schema description coverage, the baseline is high. The description adds value by clarifying canonical field names, input_class requirements, and refusals. It provides examples and rule references, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a form field - Create a new formfield record. Writes live data.' It clearly identifies the resource and action. Mentioning sibling tools (updateFormField, listFormFields) further distinguishes its specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists required parameters and provides canonical examples. It references rules and sibling tools, offering context on when to use. However, it lacks explicit 'when not to use' or alternative conditions, so it's slightly below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description states 'Writes live data' (non-read-only) and warns about duplicate creation leading to double-billing and reporting issues. Annotations show readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; description adds context about non-enforced uniqueness and client-side pre-check pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headings, bullet points, and sections. Front-loads purpose and usage. Every sentence adds value, though the caution about double-billing could be slightly condensed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key behavioral aspects: creation as manual bypass, uniqueness pre-check with client-side filtering, parameter interactions, and reference to update alternative. Does not describe return values or error conditions, but output schema is absent and annotations are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 7% schema description coverage, the description compensates by listing required fields, explaining lead_status enum and non-validation, and describing scoring fields. However, not all 15 parameters are individually explained, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a lead match - Create a new leadmatch record' with a specific verb and resource. It distinguishes from sibling 'matchLead' by noting it bypasses auto-matching for manual scenarios.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' section lists specific manual override scenarios (data migrations, manual overrides, replaying matches) and contrasts with automatic handling via 'matchLead'. Provides pre-check uniqueness pattern and alternative 'updateLeadMatch' for duplicates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent write operation, but the description adds crucial behavioral context: BD does NOT enforce uniqueness on `menu_name`, duplicates cause wrong menu rendering, and a server-side pre-check is required before creation. It also discloses the return value shape and the `_admin_edit_url` deep-link, going well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured with bolded labels (Use when, Required, Pre-check, Parameter interactions, See also, Returns). Each section serves a purpose, and there is no filler. The length is justified by the operational warnings and return details, though it could be slightly tightened without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters and no output schema, the description covers the core workflow, required parameters, critical duplicate-prevention steps, parameter interactions for key fields, and the exact return object including `_admin_edit_url`. It omits explanations for optional layout-related fields, but these are likely less critical; overall it gives an agent enough 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 0%, so the description carries the burden. It adds meaningful semantics for three of nine parameters: `menu_name` as internal identifier (max 35), `menu_title` as visible heading, and `menu_active` with 0/1 mapping. However, six other parameters (`menu_div_id`, `menu_div_css`, `menu_effects`, etc.) are left unexplained, so the description only partially compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a menu - Create a new menu record. Writes live data.' which clearly identifies the action (create), the resource (menu record), and the live-write nature. It differentiates from siblings by explicitly referencing 'createMenuItem' for adding entries and 'updateMenu' for modifying existing menus, making its purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The '**Use when:** adding a new navigation container' gives a clear condition for use. It also provides explicit alternatives: 'After creating the container, add entries via `createMenuItem`' and 'If taken: reuse via `updateMenu`, OR ask the user, OR pick an alternate `menu_name`'. This tells the agent exactly when to use this tool and when to turn to others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a write operation, and the description adds critical context: no enforced uniqueness, consequences of duplicates, and a server-side filter-find workflow. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (use when, required, pre-check, see also), but slightly verbose. Every sentence is meaningful, but could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 3 required params and no output schema, the description covers the critical pre-check logic and uniqueness risks, which is sufficient 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?
Schema coverage is 0%, but description adds meaning for group_tag_name (uniqueness importance) but does not explain added_by and updated_by (likely user IDs). Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'tag group', and distinguishes from siblings like updateTagGroup and listTagGroups by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (organizing tags into new themes, rare) and provides a detailed pre-check procedure, including alternative actions if duplicate exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint:true and idempotentHint:true. The description adds that deletion is permanent, cannot be undone, with no soft-delete via API, and specifies the return message. This adds useful behavioral context beyond annotations, though it could mention error handling for non-existent IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (use when, required, see also, destructive, returns). Every sentence adds value, and the structure makes it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single parameter, no output schema), the description is complete. It covers purpose, usage guidance, parameter requirement, behavioral impact, return value, and references a sibling tool. No critical information is missing.
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% coverage with a description for redirect_id. The description merely reiterates that redirect_id is required, without adding new semantic meaning. Baseline of 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes a redirect permanently, specifying the resource (redirect record) and action (delete by ID). It distinguishes itself from siblings like updateRedirect by noting that updateRedirect modifies without removing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use scenarios (old redirect no longer needed, conflicting rule) and points to an alternative tool (updateRedirect). It also advises confirming with the user before bulk use, which is excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint and readOnlyHint, but the description adds valuable context: 'Destructive - cannot be undone via API', 'No soft-delete via API - records removed are not recoverable', and the return format. Could mention idempotency implications, but overall strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: overview, use when, required, see also, destructive warning, returns. Each sentence is necessary and adds value. Very concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and annotations, the description covers all necessary aspects: purpose, usage context, parameter requirement, destructive behavior, return format. It is complete and provides adequate 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?
Only one parameter 'id' (integer, required). Schema description coverage is 0%, but the description specifies 'Required: id.' However, it does not clarify what the ID represents (e.g., tagrelationship record ID), though it's implied. Minimal addition beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Delete a tag relationship - Permanently delete a tagrelationship record by ID.' This distinguishes it from siblings like 'updateTagRelationship' (modify without removing) and 'createTagRelationship'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when: detaching a tag from a record.' Provides a note about CSV member_tags, refers to 'updateTagRelationship' as an alternative, and warns about destructive nature with confirmation advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explicitly labels tool as destructive and expands on annotations (destructiveHint=true). Details side effects: orphaned members, subcategories, and bound pages. Explains wrapper behavior that rejects if bound page would be orphaned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Core information is front-loaded, but description includes extensive tangential domain details (member classification, sub-sub-categories, table-name mapping). This extra content could be shortened or moved elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and no output schema, the description covers all essential aspects: action, parameter, side effects, prerequisites, return format, and edge case with bound pages. Agent has enough info to safely invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes profession_id as 'The top-level category ID to delete.' Description restates 'Required: profession_id' but adds no new meaning beyond schema. Schema coverage is 100% so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it permanently deletes a top-level member category by profession_id. Distinguished from sibling delete tools (e.g., deleteSubCategory) by specifying 'TOP-level member category'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' section: removing unused top-level category. Prerequisites: reassign orphaned members and handle subcategories. Alternatives: updateTopCategory mentioned. Addresses edge case with bound pages and wrapper rejection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds return format and notes the schema typo, adding value beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four succinct sentences with zero waste, front-loading the core purpose and then providing necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with no output schema, description provides return format, sibling reference, and explains the typo, fully contextualizing the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already includes the typo note. Description restates 'Required: locaiton_id (path)' but adds no new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single city - Fetch one city row. Read-only.' It specifies the action (get/fetch), the resource (city row), and distinguishes it from sibling tool listCities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions required parameter locaiton_id and points to listCities for enumeration/filtering alternatives, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent. The description adds details on return format ('{ status: "success", message: [{...record}] }') and error behavior (empty or 404), providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with clear sections: one-liner, use-when, required param, see also, returns. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter and no output schema, the description covers purpose, usage context, parameter requirement, return format, and error behavior. It is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% so description must compensate. It mentions click_id is required and implies it identifies the record, but does not explain its meaning further. For a single integer parameter, this is adequate but minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single click record' and specifies 'Read-only.' It distinguishes from sibling tool listClicks by indicating that this tool is for drilling into a specific record by click_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage context: 'Use when: rare - drilling into a specific click record by click_id' and contrasts with listClicks for most work. Also includes 'Required: click_id' and 'See also: listClicks'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, destructiveHint, idempotentHint. The description adds return format ('{ status: "success", message: [{...record}] }') and failure behavior (empty or 404), which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear headings (Use when, Required, See also, Returns), front-loaded with purpose, and every sentence contributes value. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, use cases, required parameter, return structure, and failure mode. No output schema needed; description is sufficient for a simple getter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description only states 'Required: lead_id,' which is redundant with the schema. Does not elaborate on the meaning or format of lead_id beyond its self-explanatory name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single lead' and 'Fetch a single lead record. Read-only.' Differentiates from listLeads (enumerate many) and matchLead (confirm before calling).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when:' scenarios (viewing details after notification, CRM follow-up, confirming existence before matchLead) and 'See also:' alternative (listLeads for enumeration).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context about the return format ('status:success, message containing one lean-shaped record') and behavior on missing (empty or 404). It also explains the lean-by-default keep-list and the effect of include_extras, which goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured with clear sections (purpose, use when, see also, returns). It front-loads the core purpose. Some redundancy ('Get a single menu item - Fetch a single menuitem record') could be trimmed, but overall it is informative and not excessively verbose for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description explains the return format and not-found behavior. It also covers the difference from the list sibling and details the optional parameter. This is sufficient for a simple read tool with clear metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 50% coverage (include_extras described, menu_item_id not). The description states 'Required: menu_item_id' and explains the include_extras parameter in detail, including what fields are restored. This adds meaning beyond the schema, especially for the undocumented menu_item_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a single menu item - Fetch a single menuitem record.' This is a specific verb+resource combination. It also distinguishes from the sibling tool 'listMenuItems' by noting that this single-record fetch does not apply the empty-link filter, making the purpose very clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: editing one specific menu entry.' It also provides a 'See also' reference to listMenuItems for enumeration. This gives clear guidance on when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by explicitly stating 'Read-only' and detailing the return format including the structure of the response for found and not found cases, which goes beyond annotation 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 concise and well-structured with clear sections: a one-line summary, a lean-by-default keep-list, usage guidelines, required parameter, see also, and return format. Every sentence is purposeful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single record fetch by ID), the description fully covers purpose, parameters, return format, error behavior, and relationship to sibling tools. Annotations cover safety, and output schema is not needed due to explicit return format description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the default keep-list fields and the purpose of 'include_marketplace' parameter. For 'photo_id', it emphasizes it is required and how to obtain it. The schema provides some description for 'include_marketplace', but the description adds contextual usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single album photo - Fetch a single portfoliophoto record.' It distinguishes the tool from the sibling 'listMultiImagePostPhotos' by explicitly mentioning 'single' and comparing to the list counterpart.
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 explicit usage context: 'Use when: editing or removing one specific photo within an album.' It also mentions the required prerequisite 'photo_id (from listMultiImagePostPhotos)' and references the sibling tool 'listMultiImagePostPhotos' for enumeration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by detailing the return format ('{ status: "success", message: [{...record}] }') and behavior when not found (empty or 404), which goes beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headings, and it is concise: four sentences covering purpose, usage, required parameter, see-also, and return information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema), the description is complete. It explains what the tool does, when to use it, what input is required, and what output to expect. Annotations cover safety and idempotency, so no gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of the single parameter (redirect_id) with a description. The description repeats that redirect_id is required, but adds context by saying 'investigating one specific redirect rule by redirect_id', which provides usage context beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single redirect' and 'Fetch a single redirect record. Read-only.' This is a specific verb and resource, and it distinguishes itself from the sibling listRedirects by focusing on one specific redirect rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: investigating one specific redirect rule by redirect_id.' and provides a see-also for listRedirects, offering clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares read-only behavior (matching annotations) and adds return format details: '{ status: "success", message: [{...record}] }' and handling of not-found cases (empty or 404). This supplements the annotations with concrete response 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 compact and well-structured, using markdown for readability. Each sentence serves a distinct purpose: what, when, required param, see also, and return format. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with one parameter, the description covers all essential aspects: operation type, usage context, required parameter, related tool, and return behavior (including error cases). No gaps remain.
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 that smart_list_id is required, but the schema already marks it required. With 0% schema description coverage, the description adds minimal value; however, the parameter name is self-explanatory given the tool's purpose, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single smart list - Fetch a single smartlist record. Read-only.' This specifies the verb (Get/Fetch) and the resource (smart list), distinguishing it from sibling tools like listSmartLists and other CRUD operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a use case: 'Use when: fetching one saved filter's config.' It also references the sibling tool listSmartLists for enumeration, guiding when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, etc. Description adds return format and empty/404 behavior, complementing annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with headings, covers all necessary information in a few lines without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, description fully covers purpose, usage, required param, alternative, and return format/behavior. No 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?
Input schema has no parameter description (0% coverage). Description mentions 'Required: id' but doesn't elaborate beyond what is obvious from context. Adequate but minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches a single tag relationship by ID, distinguishing from listTagRelationships. Among siblings, many get tools, but explicitly says 'single' and '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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: one relationship row by ID' and 'See also: listTagRelationships (enumerate many)', providing when-to-use and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false, and the description adds return format and behavior on not found, providing operational context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short (3 sentences plus return format), front-loaded with purpose, and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter and no output schema, the description covers purpose, usage, required param, return format, and not-found case. Annotations provide safety hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter 'id' is described as 'Required: id', but no additional meaning given. With 0% schema description coverage, the description should compensate but only restates requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'tag type' or 'tagtype record', and distinguishes from sibling 'listTagTypes' which enumerates many.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: one tag type by ID' and provides 'See also: listTagTypes' for enumeration, but lacks explicit when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds that it's a paginated enumeration of a global reference table, returns specific fields, and omits create/delete. Provides additional context about URL slug derivation and system-critical nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headers and front-loaded purpose. Slightly verbose due to URL slug derivation details, but still efficient and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides return structure, pagination/filter/sort details, and system-critical context. Lacks output schema but compensates with explicit return fields. Missing auto-complete use case, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description highlights useful filters (country_code, country_name, active) and explains the context of country_code for URL slugs. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists countries with pagination, distinguishes from siblings like getCountry and updateCountry, and explicitly says create/delete are omitted. It gives concrete use cases for resolving country codes and URL slugs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (resolving country codes, URL slugs) and when not to (create/delete), and directs to updateCountry for corrections. Also warns that it's a system-critical table.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by specifying that no session is started, no profile data is returned, and the response envelope is standard BD format. Annotations indicate readOnlyHint, destructiveHint, idempotentHint, which are consistent, and the description fills in behavioral details not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings and clear sections, but it repeats the point about no profile data three times. It is relatively concise considering the context, but could be slightly more efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter login tool with no output schema, the description covers the return format, use case, and next steps. It lacks error handling details but is sufficient for an agent to use correctly. The workflow guidance compensates for missing schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It lists required parameters (email, password) and notes they are required, but does not elaborate on their meaning or constraints beyond what the schema format provides. The parameter interaction note about no profile data is helpful but not per-parameter. Adequate but lacks depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates user credentials (email/password) and explicitly distinguishes it from related tools by noting it does not return profile data, directing the agent to use getUser instead. The verb 'validate' and resource 'credentials' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'when implementing SSO or a custom login flow' and clarifies it does not start a web session. It also gives clear after-use guidance to follow with getUser or listUsers, differentiating from sibling tools like verifyToken or createUser.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true and idempotent=true. The description adds value by detailing pagination, limit caps with heavy include flags, profile URL construction, and the lean-by-default keep-list. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with headings (Use when, Pagination, etc.) and front-loaded with purpose. It could be slightly more concise, but the structure helps navigate the complexity of 21 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers output format, pagination, sort enums, and profile URL construction. Missing details: default sorting order, exact pagination fields. Overall quite complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (76%), but the description adds meaningful context: groups parameters, explains interactions (q matches specific fields, address+dynamic for proximity), and clarifies the role of include_extras. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs full-text search across members with filters. It explicitly distinguishes itself from sibling tools like listUsers (exact-field lookup) and getUser (single record), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' scenarios (public member-search, SEO audits, keyword/category/location lookup) and explicitly advises against using it for exact-field lookups, directing to listUsers instead. It also explains parameter interactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds important behavioral details: 'Fields omitted are untouched' (partial updates) and 'Writes live data' (immediate effect). It also describes the return value including _admin_edit_url and instructs to surface it, providing actionable context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold section headers (Use when, Required, See also, Returns), making it easy to scan. It is slightly longer than necessary but each section adds value, particularly the detailed return explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 5 parameters and no output schema, the description covers purpose, usage, required parameter, return value, and even provides a user-facing instruction about the admin edit link. It lacks explicit error-handling details, but this is acceptable for a CRUD 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 coverage is low (20%), and the description partially compensates by mentioning menu_id as required and referencing menu_active toggling. However, it does not explicitly explain menu_name vs. menu_title, leaving some ambiguity. The _clear_fields parameter is well-described in the schema, so that does not need repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update a menu - Update an existing menu record by ID.' It uses a specific verb and resource, and explicitly distinguishes itself from siblings by mentioning 'See also: createMenu (add new), deleteMenu (remove permanently).'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios: 'Use when: renaming a menu, toggling menu_active, or adjusting its CSS/HTML wrapper attributes.' It also states the required field and names alternative tools, making it clear when to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate not read-only and not destructive, but the description adds meaningful behavior: 'Writes live data' and 'Fields omitted are untouched' (partial update). It also discloses the return format. No contradictions with annotations, and the extra details about enum semantics add transparency beyond the 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 structured with bold labels (Use when, Required, Enums, See also, Returns), making it scannable. Every section serves a purpose: use cases, required ID, enum reference, sibling tools, and return value. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 13 parameters and no output schema, the description covers the key contextual needs: when to use, what the partial-update behavior is, what the review_status enums mean (including the undocumented value 1 caveat), and what the response will look like. Combined with annotations, it provides a complete operational picture.
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 low (15%), so the description must compensate. It thoroughly explains review_status enums and notes required review_id, but the rating fields, recommend, and text fields are only implicit from the 'typos' use case. The partial-update note ('Fields omitted are untouched') provides general parameter behavior, but individual field meanings are not fully elaborated.
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 opens with 'Update an existing review record by ID' — a clear verb+resource pair. It distinguishes from siblings by explicitly mentioning createReview and deleteReview in 'See also', and the top line 'Update a review' makes the action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'Use when: moderating - change review_status... Also used for admin corrections of typos in review text.' It also provides alternatives via 'See also: createReview (add new), deleteReview (remove permanently)', giving clear when-to-use vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotentHint and openWorldHint. Description adds valuable context: 'Fields omitted are untouched', 'Writes live data', return format, and detailed _clear_fields behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear headings (Use when, Required, Enums, See also, Returns). No wasted words, front-loaded purpose, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given openWorldHint and no output schema, description covers behavior (untouched fields, live data), return format, and clearing fields. References related tools. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%). Description clarifies required id and definitive enum values, but mostly repeats schema description for _clear_fields. Does not add new information about other potential parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update an unsubscribe record' with specific verb and resource. Distinguishes from siblings like createUnsubscribe and deleteUnsubscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: editing an unsubscribe record. Rare.' and provides 'See also:' with alternative tools. Includes required parameter id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, confirming mutation. The description goes beyond by stating 'Writes live data' and 'changes are immediately visible on the public site.' It also explains the auto-suffix safety net for filename collisions and the return format, adding behavioral context not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections (purpose, usage, pre-check, parameter guidance, see also, returns, classification). Every sentence adds value given the tool's complexity and the need to differentiate from alternatives. Some extra context on member classification could be moved to a separate reference but is still relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, openWorldHint=true), the description is remarkably complete. It covers usage scenarios, pre-check steps, parameter details, uniqueness constraints, return format, and even explains how member classification works in the broader system. No gaps are apparent.
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 50% (only 4 of 8 parameters have descriptions). The description compensates by explaining each parameter in plain language (e.g., name, profession_id, master_id, filename). It adds usage context beyond the schema, such as the meaning of master_id for sub-sub-categories and the need for profession_id to link to a Top Category.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a service - Create a new SUB-level member category under an existing Top Category.' It distinguishes itself from sibling tools like createTopCategory (which creates parent categories) and provides context on hierarchy levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('explicitly adding a sub-category BEFORE assigning members to it') and when not to (use createUser or updateUser with auto-creation). It names alternatives like createUser, updateUser, and updateSubCategory. It also gives pre-check instructions for filename uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint, idempotentHint), description adds that delete is permanent, cannot be undone via API, no soft-delete, and child fields become orphaned. This gives critical 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with clear sections (use when, required, see also, destructive, returns). Each sentence adds value. Slightly verbose with return format example but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter, description covers purpose, usage, behavior, return format, and warnings. No output schema needed because return is clearly described. Complete for 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 has one parameter with 0% coverage, but description explicitly states 'Required: form_id' and 'delete a form record by ID.' However, it does not add further constraints or format details beyond what the schema indicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a form - Permanently delete a form record by ID.' The verb 'delete' and resource 'form' are specific. It distinguishes from sibling tool `updateForm` which modifies without removing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when: removing a form - child fields orphan.' and 'See also: updateForm (modify without removing).' Also advises confirming intent with user before bulk use, covering when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), description confirms 'Permanently delete', 'cannot be undone', 'No soft-delete', and warns to 'confirm intent before bulk use'. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: summary line, usage guidance, required field, destructive warning, return info. No fluff. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple input schema and rich annotations, description covers all needed aspects: purpose, when to use, behavioral warnings, return format. Sufficient for agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single required parameter lead_id, schema coverage 0%. Description only repeats 'Required: lead_id' without adding meaning (e.g., format, source, or constraints). Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb and resource: 'Delete a lead - Permanently delete a lead record by ID.' Distinguishes from siblings like deleteClick by specifying 'lead'. Mentions alternative updateLead for preservation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use: 'removing a spam or test lead.' Provides alternative: 'use updateLead with a status change instead.' Also references updateLead in 'See also.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: specifies permanent deletion, no soft-delete, records unrecoverable. Warns about unsent email. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, usage sections, and warnings. Slightly verbose but each sentence adds value. Score 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-param tool with no output schema, the description covers purpose, usage, behavioral traits, parameter, and return format. 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?
Single parameter match_id is mentioned as required, but no additional details beyond schema. Schema coverage is 0%, so description adds minimal value—baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (Delete) and resource (lead match), with explicit mention of permanence. Differentiates from siblings like updateLeadMatch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (cleaning up erroneous matches, removing auto-created matches) and warns about side effects (does not unsend notification email). References alternative updateLeadMatch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveHint: true, but the description adds crucial context: records are irrecoverable, no soft-delete, and advises user confirmation before bulk use. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Six terse sentences, front-loaded with purpose, then usage, required param, alternative, warnings, and return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple tool, the description covers purpose, usage guidance, behavioral implications, required parameter, and expected output. Sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It only repeats 'Required: photo_id' from the schema, adding no meaning about what the ID represents or how to obtain it. The name implies the parameter is the photo ID but does not confirm or describe constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an album photo permanently by ID. It specifies the resource ('portfoliophoto record') and distinguishes it from sibling update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides use conditions: 'permanently removing one photo from an album' and contrasts with hiding via updateMultiImagePostPhoto. Also includes a 'See also' reference to the modification sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals destructive behavior beyond annotations: it cannot be undone via API, removes the post_token, and breaks external links. Annotations already indicate destructiveHint=true, but the description adds specific, actionable side effects. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headers and sections, but it is slightly verbose. Each sentence serves a purpose, but some phrases (e.g., repeated warnings about destructiveness) could be condensed. Overall, it is efficient and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's operation: it explains the return value (status and message), side effects (link breakage), and how it differs from alternatives. For a single-parameter delete tool with no output schema, it provides all necessary context 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?
With only one parameter (post_id) and 0% schema description coverage, the description merely restates that post_id is required. It does not explain the parameter's format, range, or examples of valid values, which would add value. However, given the simplicity of the parameter, the description is minimally adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a post - Permanently delete'), identifies the resource by ID, and distinguishes it from the sibling tool updateSingleImagePost for hiding posts. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Use when: removing a post permanently') and when not to use it (for hiding, use updateSingleImagePost with post_status=0). It also recommends confirming intent with the user before bulk use, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), describes orphaning of rel_tags, no soft-delete, non-recoverability, and required user confirmation for bulk use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bolded key phrases, but slightly verbose. Every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a single-parameter tool with annotations. Covers return value, side effects, and 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?
Only parameter 'id' is mentioned as required, but schema already covers type and required. Schema coverage is 0%, so description adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a tag - Permanently delete a tag record by ID,' specifying the action (delete) and resource (tag). It differentiates from siblings like updateTag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: removing a tag entirely' and 'See also: updateTag (modify without removing).' Also adds caution for destructive operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds key behavioral details beyond annotations: 'Permanently delete', 'cannot be undone via API', 'No soft-delete via API - records removed are not recoverable.' Consistent with destructiveHint=true. No contradiction with idempotentHint=true (delete is idempotent).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: summary, use case, required param, alternatives, destructive warning, return format. Every sentence adds value, and key points are front-loaded. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, usage context, behavioral traits, and return value. Annotations are present, and the description complements them well, addressing consent and bulk use concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter is 'id', and schema description coverage is 0%. The description merely repeats 'Required: id.' without explaining what the id represents or any constraints. Given low coverage, additional param context is needed but missing.
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 'Remove email from unsubscribe list - Permanently delete a unsubscribe record by ID.' The verb 'delete' matches the tool name, and it specifies the resource (unsubscribe record), distinguishing it from other delete tools like deleteClick or deleteForm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Use when: re-subscribing a member (remove their unsubscribe entry).' Warns against misuse: 'Confirm the member's consent first - don't use to silently re-enable emails.' Provides alternative: 'See also: updateUnsubscribe (modify without removing).' Adds caution for bulk use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, idempotentHint=true. The description adds that the tool is 'Read-only' and explains the resolution of system_name to data_id via listPostTypes. It also mentions the return format and behavior when not found (empty or 404). No contradictions. Excellent transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (bold headers) and is informative without being overly verbose. Each sentence adds value. It is slightly longer than necessary but remains focused and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description details the return format: '{ status: "success", message: [{...record}] }' and behavior for not found. It also covers parameter interactions, use case, and even addresses the lack of a create endpoint for dropdown values. This is comprehensive for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds meaning by explaining the mutual exclusivity requirement: 'exactly one of data_id OR system_name'. It also describes how system_name is resolved and that data_id comes from listPostTypes. This provides context beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get custom fields for a post type - Fetch a single posttypecustomfields record.' This clearly states the action and resource, distinguishing it from siblings like createPostType or deletePostType. The purpose is unambiguous and precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when: building a create/update payload for a post type that has custom fields (most do).' This gives a clear use case. However, it does not specify alternatives or when not to use, but the context is sufficient. Score 4 for clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds useful behavior like truncation of review_description and the effect of include_full_text, along with response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headers, front-loaded purpose, and efficient sentences. Slightly verbose on return format but overall concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers tool usage, parameters, return behavior, and sibling references. No output schema, but description provides enough context for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers include_full_text with description, but the description explains truncation details and mentions review_id as required. Adds practical context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single review' and 'Fetch a single review record', specifying the verb and resource. It distinguishes from sibling tools like listReviews (bulk) and mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: investigating one specific review...' and directs to listReviews for bulk moderation, providing clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds return format and not-found behavior ('Returns: { status: "success", message: [{...record}] } … Empty or HTTP 404 when not found'), enhancing behavioral disclosure beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Purpose, Use when, Required, See also, Returns) and is concise, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple Get-by-ID tool with one parameter and no output schema, the description covers purpose, usage, required parameter, alternative tool, and return format, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. However, it only repeats 'Required: id' which is already in the schema. It adds no explanation of what 'id' represents (e.g., the unique identifier of the tag group), providing minimal added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single tag group - Fetch a single taggroup record. Read-only,' using a specific verb and resource. It distinguishes itself from sibling 'listTagGroups' by stating 'See also: listTagGroups (enumerate many).'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly includes 'Use when: fetching one tag group by ID' and 'Required: id,' plus references 'listTagGroups' as an alternative, providing clear guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description goes far beyond by detailing pagination, filter/sort behavior, date handling, raw vs parsed output, and WAF considerations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with bold headers and bullet points. Given the tool's complexity, the verbosity is partly justified, but could be more concise by trimming some examples and merging repetitive notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all aspects: input parameters, filtering, sorting, pagination, date quirks, relation to `getForm`, return format, and WAF notes. For a tool with 8 parameters and no output schema, this is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds significant meaning: explains `page` as cursor from previous response, `include_raw` transforms output, filter patterns, date operators, and compound filters. Provides concrete examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List Forms Inbox submissions' and 'Read-only', establishing a specific verb and resource. It distinguishes from sibling tools like `getFormInquiry` (single submission) and `listForms` (list forms) via the 'See also' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when: reading contact-form and lead submissions' and provides a detailed search example. It lacks explicit when-not-to-use but the read-only nature and sibling references imply alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds critical behavioral details beyond annotations: empty-state quirk with non-standard error response and normalization, pagination (cursor-based), filter/sort behavior with silent drops, return shape. Annotations already declare safe read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for use-case, empty-state, pagination, filter/sort, and returns. Slightly long but every sentence adds value; front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a list tool with 7 parameters and no output schema. Covers pagination, filtering, empty state, return format, and references external rules. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds context about silent drops for wrong property names, compound filter arrays, and rule references, improving usability beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists lead matches with pagination, and specifies it is read-only. Distinct from sibling tools like getLeadMatch or listLeads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (auditing, billing reports, explaining notifications). Does not directly mention when not to use or compare to sibling list tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms read-only nature and explains that create/update/delete are deliberately omitted. It details the response fields and mentions pagination, filter/sort, and merging behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately lengthy but well-structured with sections and priority ordering. Each sentence adds value. It is appropriately sized for the complexity, though slightly verbose in places.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists all returned fields. It explains the data scope (custom vs master), use case, response structure, pagination/filter standard, and merging behavior. References to rules provide additional context. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description does not add new parameter information beyond what the schema already provides, so baseline 3 is appropriate. It mentions 'standard pagination + filter/sort' but this is generic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List custom sidebars - Paginated enumeration of CUSTOM sidebars defined on this site.' It specifies that create/update/delete are omitted, distinguishing it from write operations. It contrasts with sibling tools like 'getSidebar' by being a list endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly says 'Use when: an agent needs to set form_name on a WebPage... and wants to verify a custom sidebar name exists.' It also warns that this endpoint returns only custom sidebars, not master default ones, and directs to Rule: Sidebars for the master list and workflow. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, etc. Description adds behavioral context beyond annotations: pagination semantics (cursor-based), filter/sort behavior (silent-drop, derived-field unfilterability), and references to external rules. Some redundancy (repeats 'Read-only') but overall valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings (Use when, Pagination, Filter/sort, See also, Returns). Front-loaded with purpose. Slightly verbose due to detailed operator lists but each section is purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 7 params and no output schema, description covers pagination, filter/sort, return format, and cross-references rules. Missing some details like default sort order but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, baseline 3. Description adds significant context: pagination params (cursor usage, next_page), filter/sort params (operator list, compound filter arrays, silent error behavior). Goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it lists smart lists (paginated enumeration of smartlist records) and distinguishes from getSmartList (single record by ID). Clearly identifies verb, resource, and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly includes 'Use when:' enumerating saved dynamic filter configurations and references getSmartList as an alternative for single records, providing clear guidance on when to use this tool vs siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds significant context: pagination semantics (cursor-based, limit/page), filter operator details, silent-drop detection for invalid property names, and compound filter support. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (summary, use-when, pagination, filter/sort, see also, returns). It is front-loaded with the core purpose and each sentence contributes value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, pagination, filtering) and no output schema, the description covers output format and key behaviors. However, it references external rules (Rule: Pagination, Rule: Filter operators) which may not be accessible, slightly reducing completeness for agents without those rules.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description enriches parameters by explaining pagination, filter operator behavior (including silent drops and compound filters), and ordering. This adds meaning beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List tag relationships - Paginated enumeration of tagrelationship records. Read-only.' and explicitly distinguishes from sibling `getTagRelationship` (single record by ID). It also mentions filtering by tag or target record, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use when:' section specifying 'auditing which tags are attached to which records' and suggests `getTagRelationship` for single-record lookup. It does not explicitly state when not to use, but the use case is well-defined and alternatives are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds cursor-based pagination semantics, filter operator behaviors (silent-drop detection, derived-field unfilterability), and return format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, front-loaded with purpose, and each sentence adds context. It is slightly long but justified by the complexity of pagination and filtering.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, but rich annotations, the description covers pagination rules, filter operators, return format, and silent-drop behavior. It is complete for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but the description adds meaning beyond raw schema: it explains cursor pagination (use next_page), filter operator word-forms and silent-drop, compound filter pairing, and sorts. This adds significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists user photos with pagination, is read-only, and distinguishes from getUserPhoto (single record). It specifies filtering by user_id and enumerates photo types (profile, logo, cover).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use when: enumerating photos attached to members' and provides filter/sort guidance, pagination rules, and a see-also to an alternative tool. This gives clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true. The description adds behavioral context: fields omitted are untouched, and the return format is specified. It does not repeat side-effect warnings from the schema (e.g., top_id orphan matches), which is acceptable since the schema covers those. However, a brief mention of idempotent behavior could further enhance 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 concise and well-structured with bullet points and sections. It front-loads the main purpose and keeps each sentence purposeful. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no output schema), the description provides necessary context: return format, custom field handling, and links to related tools. It does not cover every behavioral edge case, but the schema with 92% coverage fills gaps. A note about lead_matches impact could improve completeness, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (92%), so baseline is 3. The description adds value by highlighting the required lead_id, explaining the return format, and clarifying custom field storage. It does not describe each parameter, but the schema already provides detailed descriptions. Overall, it supplements the schema effectively.
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 uses a specific verb ('Update') and resource ('lead'), clearly states it updates an existing lead record by ID, and distinguishes itself from sibling tools like createLead, deleteLead, matchLead, and updateUserMeta by mentioning them in 'See also'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Update an existing lead record by ID'), notes that omitted fields are untouched, indicates the required parameter (lead_id), and provides guidance on handling custom fields via updateUserMeta/createUserMeta, including a reference to related rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds key behaviors: 'Fields omitted are untouched', 'Writes live data', and explains that the 'type' field is wrapper-managed and always 'custom'. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings and concise paragraphs. Every sentence adds value—no fluff. Front-loaded with the core action, then usage guidance, then parameter notes, and finally return info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no output schema, but annotations present, the description covers the core behavior, usage context, type management, and return format. It lacks an explicit mention of idempotency but that's already annotated. Very good completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by highlighting the required parameter (redirect_id) and explaining the special _clear_fields parameter behavior, which is not detailed in the schema. This helps an agent understand how to clear fields correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing redirect by ID, with the distinctive behavior 'Fields omitted are untouched.' It distinguishes from sibling tools like createRedirect and deleteRedirect by specifying it updates an existing record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'adjusting an existing rule's destination or source path' and notes it's rare. Provides alternatives: 'See also: createRedirect (add new), deleteRedirect (remove permanently).' This perfectly guides selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral details beyond annotations: 'Fields omitted are untouched', 'Writes live data', and the wrapper-managed audit-trail field. Annotations already indicate idempotent and non-destructive, but description enriches understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear header, bullet points, and front-loaded information. It is efficient without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: purpose, usage, parameters, return value, and special behaviors like wrapper-managed fields and clearing mechanism. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Low schema description coverage (33%) is compensated by description explaining 'id' as required, 'tag_name' as optional, and detailed behavior of '_clear_fields'. Adds context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a tag' and explains it updates an existing tag record by ID. It distinguishes itself from siblings by mentioning createTag and deleteTag in 'See also'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance with 'Use when: renaming a tag without losing tag-to-member relationships.' Also specifies required parameter 'id' and mentions wrapper-managed 'updated_by' field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a write operation (readOnlyHint: false, idempotentHint: false). The description adds meaningful context: 'Writes live data,' explains the default review_status flow ('0 Pending -> admin review'), and warns about omitted rating fields defaulting to 5. It does not detail all side effects, hence not 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then usage guidance, required fields, parameter interactions, and a cross-reference. Every sentence provides distinct value; no fluff or repetition. It is compact despite covering many critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter create tool with no output schema, the description plus schema form a complete picture. It covers use cases, required fields, key parameter interactions, default behaviors, and sibling relationships. The absence of an output schema is acceptable for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 62%, so the schema does substantial work. The description adds value by clarifying user_id ('the member being reviewed'), recommend ('0=No, 1=Yes'), and review_status semantics ('controls initial visibility'). It also highlights required parameters. This compensates for undocumented fields like review_title and review_description.
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 opens with 'Create a review - Create a new review record. Writes live data.', which clearly states the action (create) and resource (review record). It distinguishes from siblings by explicitly contrasting with updateReview ('See also: updateReview (modify existing)') and by clarifying that real member-submitted reviews go through the BD form, not this API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when:' section explicitly lists three appropriate scenarios (importing legacy reviews, placeholder/test data, external integration) and an exclusion: 'only use this API when bypassing that form.' It also points to updateReview for modifications. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds that deletion is permanent, unrecoverable, requires user confirmation for bulk use, and does not affect click counter, all beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: action, usage, required param, see also, destructive warning, return format. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with no output schema, the description covers purpose, usage, parameter, side effects, and return format. No evident gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It names the required parameter 'click_id' and provides context for its use, but does not elaborate beyond the name. Still adequate for a simple integer ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Delete' and resource 'click record', and specifies 'by ID'. It distinguishes from siblings like 'updateClick' and other delete tools by focusing on click records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when:' section for removing test/spam clicks, states what it does NOT affect (member click counter), and suggests 'updateClick' as alternative for modification without deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description details that records referencing a deleted data type may become orphaned and advises user confirmation. Also specifies the return format for the delete 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 concise and well-structured with bullet points. It front-loads the purpose and each sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple tool with one parameter, no output schema, and annotations covering destructive nature, the description provides sufficient context including side effects and return format. It meets all needs for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (data_id) with 100% schema description coverage. The description adds minimal extra meaning beyond the schema, simply restating 'Required: data_id'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a data type definition, using a specific verb and resource. It distinguishes from sibling tools like updateDataType by mentioning modification without removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (removing an unused data type), warnings about orphaned records, and mentions of required data_id. Also references updateDataType as an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. The description reinforces destruction: 'Permanently delete', 'cannot be undone via API', 'records removed are not recoverable.' It adds context about system template fallback and user confirmation, going beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear segments: purpose, use case, required param, see also, destructive warning, return format. Every sentence adds unique value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with one parameter and no output schema, the description covers all relevant aspects: what it does, when to use, required parameter, destructive behavior, return format, and potential system impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It states 'Required: email_id.' but does not elaborate on its meaning (e.g., the ID of the template to delete). Since the parameter name is self-explanatory and only one parameter exists, this is minimally adequate, scoring 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an email template - Permanently delete a emailtemplate record by ID.' It specifies the verb (delete), resource (email template), and nature (permanent). Among sibling tools, it is distinct because it targets email templates specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use when: removing a deprecated template.' It warns about potential fallback to defaults if a required system template is deleted. Also notes 'confirm intent with the user before bulk use' and provides an alternative: 'See also: updateEmailTemplate (modify without removing).'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes destructive nature ('cannot be undone via API'), which matches the destructiveHint annotation. Also details what is removed and what is not affected, and provides the return value. Adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains several paragraphs of extra context about database schema and other tools, which dilutes conciseness. The essential information is front-loaded, but the additional details could be moved to a reference document.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive tool, the description covers purpose, usage guidelines, behavioral implications, and return value. It also provides broader context about member classification, which is helpful for understanding the tool's role.
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 single parameter 'rel_id' is described as the required identifier, and its role is clear from context. However, the description could specify that it corresponds to the link row ID in the join table, though the purpose is still well-understood.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('permanently delete a Member ↔ Sub Category link'), the resource ('rel_services' join table), and the required identifier ('rel_id'). It distinguishes itself from siblings like createMemberSubCategoryLink and updateMemberSubCategoryLink.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('removing a specific link row') and what it does NOT do ('Does NOT update the users_data.services CSV'), with alternative instructions ('update it via updateUser').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, but description adds critical context: permanent deletion, no recovery, need for user confirmation before bulk use, and return format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, well-structured with clear sections: purpose, use-when, required, see-also, destructive warning, returns. Every sentence serves a purpose without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema), the description fully covers what an agent needs: purpose, usage guidelines, behavioral traits, parameter requirement, and return. Complete for effective 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 has 0% description coverage and only one parameter (review_id). The description mentions 'Required: review_id' but adds no additional meaning (e.g., type, format, source). Carries the burden but barely adds value beyond the schema's property name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a review - Permanently delete a review record by ID.' It uses a specific verb and resource, and distinguishes from siblings like updateReview by contrasting destructive deletion with hiding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('when the review content violates policy and must be purged') and when not to use ('For 'hide without removing' use updateReview'). Provides an alternative tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), description adds critical details: 'cannot be undone via API,' 'records removed are not recoverable,' and return format. This provides full transparency for a destructive 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?
Description is well-structured with clear sections (main, use when, required, see also, destructive behavior, returns). No extraneous text; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description covers all necessary aspects: purpose, usage context, parameter, alternative, destructive implications, and return value. No 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?
With 0% schema coverage, description states 'Required: smart_list_id' and implies it is the ID of the smart list to delete. Adds minimal meaning beyond the parameter name; lacks further details like format or source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a smart list - Permanently delete a smartlist record by ID.' The verb 'delete' and resource 'smart list' are explicit. Differentiates from sibling 'updateSmartList' via 'See also' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use when: removing a saved filter configuration.' Also directs to an alternative tool ('updateSmartList' for modification) and warns about destructive nature for bulk use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description details what becomes orphaned (users_data.services CSV, rel_services rows) and the bound-page rejection behavior. This adds significant context over annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy and includes tangential background on member classification and missing create tools. While the key points are front-loaded, the extra information reduces conciseness for this specific tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the return format, destruction semantics, orphan handling, and bound-page caveat. It fully informs an agent of all important side effects and usage conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage 0%, the description must explain service_id. It states 'Required: service_id' but does not explicitly define the ID. However, context makes it clear that it is the identifier of the sub-category. Almost sufficient, but could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a service - Permanently delete a SUB-level member category by service_id.' This distinguishes it from sibling delete tools like deleteTopCategory, with specific verb (delete) and resource (sub-level category).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: removing an unused sub-category.' and warns about orphaned references. Also suggests updateSubCategory as an alternative and details bound-page caveat, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations: emphasizes permanence ('cannot be undone via API'), describes impact on child tags (orphaning), and states no soft-delete. Contradicts none of the annotations (destructiveHint, idempotentHint, etc.) and adds crucial 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?
Efficiently structured with bold headings, each sentence earns its place. Front-loaded with main action, no redundant phrases. Approximately 100 words covering purpose, usage, behavior, parameters, and return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers a simple delete operation: describes action, side effects (orphaned children), irreversibility, required parameter, return format. No output schema needed; description provides sufficient context. Sibling tools are many, but this description uniquely addresses its role.
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?
With 0% schema description coverage, the description carries full burden but only notes that 'id' is required and mentions it in the return format. Does not explain what 'id' represents (e.g., the ID of the tag group to delete). Schema itself is minimal (integer, required), so description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb+resource: 'Delete a tag group' and specifies permanent deletion. Differentiates from siblings like deleteTag and updateTagGroup by explicitly naming the resource and providing a 'See also' link to the update alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use case: 'removing a group - child tags orphan; delete or re-group them first.' Warns about destructive nature and need for user confirmation before bulk use. Suggests updateTagGroup as alternative, fulfilling when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Exceeds annotation's destructiveHint by detailing side effects like broken shortcodes and recommends auditing with listWidgets, adding significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headings, bullet points, and separate sections for usage, caveats, and see also. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensively covers purpose, destructive nature, prerequisites, side effects, output format, and alternative, leaving no obvious 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?
Only mentions that widget_id is required, which is already in schema. With 0% schema coverage, minimal additional semantic value is provided, but the parameter is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Delete' and resource 'widget', and distinguishes from sibling 'updateWidget' by mentioning an alternative for disabling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (removing unused widget) and when not to use (disable via updateWidget), along with a practical alternative and an audit suggestion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark as read-only. Description adds return format details: 'Returns: { status: "success", message: [{...record}] }' and mentions empty/404 when not found. This enriches behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with front-loaded title, uses bullet points for key sections, and every sentence adds value. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter read-only tool with no output schema, the description covers purpose, usage, return format, and error case. Complete given context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter description 'Data type primary key'. Description restates requirement for data_id but adds no new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get a single data type - Fetch a single datatype record.' It clearly identifies the verb (get) and resource (data type), and distinguishes from sibling listDataTypes by specifying it fetches a single record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: fetching one data type's record by ID.' and provides 'See also: listDataTypes (enumerate many).' This gives clear context for when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, destructiveHint, idempotentHint. Description adds details: lean-by-default keep-list, flags to restore more data, return format (status, message array), and behavior on not found (empty or HTTP 404). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections. Front-loaded purpose, then keep-list, use cases, and return format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully explains the return shape, lean default behavior, and how to control output via flags. Provides guidance on related tools for photos. Sufficient for agent to correctly invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 83% of parameters with descriptions. Description adds value by explaining the lean keep-list and the purpose of each include flag, especially the extras bundle. It also reiterates group_id is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches a single album group/portfoliogroup record. Distinguishes from sibling tools like listMultiImagePosts (enumerate many) and listMultiImagePostPhotos (load photos separately).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use when fetching one multi-image post by group_id and that photos are loaded via listMultiImagePostPhotos. Provides a 'See also' link to listMultiImagePosts. Does not explicitly list when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds pagination behavior, cursor-based mechanics, filter silent-drop detection, derived-field unfilterability, and return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for usage, pagination, filter/sort, see also, returns. Front-loaded with purpose, no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, description covers pagination, filtering, return format thoroughly. References external rules for deeper detail, sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage. Description adds context: pagination cursor usage, filter parallel arrays, wrong name silently returns empty. Enhances understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists click records with paginated enumeration, read-only. Distinguishes from sibling getClick (single record) and other create/update/delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: pulling click-tracking analytics for reports; filter by user_id for single member. References pagination/filter rules but lacks explicit when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context beyond annotations: cursor-based pagination (limit, page), filter/sort mechanics, silent-drop detection, derived-field unfilterability, and the exact return structure. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly structured with headings, bullet points, and clear sections. Every sentence adds value, and it is appropriately sized for the tool's complexity. It front-loads the core purpose and uses references to external rules to avoid redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, pagination, filters, and no output schema), the description covers all essential aspects: when to use, pagination behavior, filter/sort details, return format, and key rules. It references relevant rules for full depth, making it complete 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% with detailed parameter descriptions. The description does not add significant meaning beyond the schema; it references external rules (Rule: Pagination, Rule: Filter operators) and mentions compound filter behavior, but the schema already explains that. Baseline 3 is appropriate since the schema carries the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List leads - Paginated enumeration of lead records. Read-only.' It specifies the verb (list), resource (leads), and key characteristic (paginated, read-only). It distinguishes from sibling tools like getLead by stating 'For fetching one lead by ID use getLead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'pulling the admin's lead inbox, generating lead reports, or iterating all leads to push into a CRM.' It also explicitly tells when not to use it and suggests an alternative: 'For fetching one lead by ID use getLead.' This gives clear guidance on when to use vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the lean-by-default keep-list, default empty-link filter, pagination behavior, filter operator details, and the merging of site records and platform master defaults. This adds significant context beyond the annotations (readOnlyHint, idempotentHint). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is quite long with multiple paragraphs and references to external rules. However, it is well-structured with bold headings, bullet points, and clear sections, making it easy to scan. It could be more concise without losing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description thoroughly covers the return format, pagination, filtering, default behaviors, and data merging. For a list tool with 9 parameters and complex defaults, this is highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default behaviors of include_empty_links and include_extras, and the filter operator semantics, which go beyond the schema descriptions. However, the schema already provides good descriptions, so the increment is modest.
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 starts with 'List menu items - Paginated enumeration of menuitem records. Read-only.' This clearly states the verb (list) and resource (menu items), and distinguishes it from siblings like getMenuItem by mentioning 'See also: getMenuItem (single record 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: enumerating items in a menu - always filter by menu_id. Use master_id filter for sub-menu items.' It also provides guidance on when to opt in to include_empty_links and include_extras, and references rules for filters and pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral details: pagination semantics (cursor-based with limit/page), filter operator rules, compound filter structure, and the exact return format. This goes beyond what annotations provide, though a brief note on rate limits or error conditions would improve it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, use-when, pagination, filter/sort, see also, and returns. Each sentence adds necessary detail without redundancy. Uses bold headings and bullet-like formatting for readability. Appropriately sized for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and many sibling tools, the description is highly complete. It covers usage context, pagination behavior, filter/sort mechanics, return format, and cross-references. For a list tool, it provides all information needed for an AI agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enhances understanding by explaining pagination cursor usage, filter operator semantics (with examples like 'eq, ne, lt'), compound filter pairing, and silent-drop detection. It references comprehensive rules for pagination and filter operators, adding meaning beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List redirects (301) - Paginated list of all 301 redirect rules on the site.' It uses a specific verb (list) and resource (redirects), and distinguishes from sibling tools like getRedirect by noting it's for multiple records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides use cases: 'Use when: auditing existing 301 rules - useful before bulk URL changes to avoid duplicate rules, or when debugging why a URL unexpectedly redirects.' Also includes a cross-reference to getRedirect for single record retrieval, offering clear context and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral details: pagination cursor semantics, silent-empty returns on wrong property/order_column names, reference to filter operator rules, and the exact return format. This goes well beyond annotations and preempts common pitfalls.
Agents need to know what a tool does to the world before 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 compact yet comprehensive, structured with clear sections: purpose, use case, pagination, filter/sort, see also, and return format. It is front-loaded with the most critical info and every sentence adds unique value. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description fully specifies the return format. All parameters are thoroughly documented in the schema, and the description covers behavioral nuances. For a read-only enumeration tool, the description provides everything an agent needs to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to use the pagination cursor (use next_page), default/max limits, and referencing external rules for filters and operators. It also clarifies the intended use of 'property' arrays for AND conditions. This extra context earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List tag groups - Paginated enumeration of taggroup records. Read-only.' It identifies the verb (list), resource (tag groups), and scope (paginated enumeration). It also distinguishes from the sibling 'getTagGroup' via the 'See also' note, making the purpose unmistakable.
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 states 'Use when: discovering the tag groupings before creating tags - each tag belongs to a group.' This tells the agent when to invoke the tool. It also references 'getTagGroup' as a single-record alternative, but does not explicitly list when not to use or other exclusions, which is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds significant behavioral context beyond annotations: pagination (cursor-based, return structure), filtering/sorting rules (silent-drop, derived-field unfilterability), and return format. Annotations already indicate read-only, idempotent, open-world, non-destructive, so description complements them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections: summary, use-when, pagination, filter/sort, see-also, returns. Each section is concise and front-loaded with essential information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, pagination, filtering), the description is thorough. It covers usage context, pagination mechanics, filter behavior, sort, return format, and edge cases. No output schema exists, so return description is necessary and provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters are described in schema (100% coverage), so baseline is 3. Description adds value by referencing rules for pagination and filtering, explaining return structure, and noting silent-drop behavior for wrong names, thus enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'List tags - Paginated enumeration of tag records. Read-only.' providing a specific verb and resource. It distinguishes from categories and the getTag sibling, making the tool's purpose clear and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when:' section explicitly states use cases: enumerating member tags, fetching tag names for display, or building a tag-management UI. It contrasts with categories and getTag, but does not cover when to use alternative list tools like listTagGroups or listTagRelationships.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds critical behavioral details beyond annotations: pagination semantics (cursor-based with limit/page), filter/sort behavior with silent-drop detection for invalid columns, and the exact return structure. It also references rules for operators and derived-field unfilterability, providing comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, use case, pagination, filter/sort, see also, returns). It is concise with no redundancy, and the most important information (purpose) is front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters with full schema coverage, no output schema, and annotations, the description provides complete context: it explains pagination, filter/sort intricacies, return format, and references rules for operators. The agent can correctly invoke the tool without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that pagination is cursor-based, that wrong filter column names silently return empty, and that filter operators have specific semantics with references to rules. These insights go beyond the schema descriptions, enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List tag types - Paginated enumeration of tagtype records' and mentions it is read-only, which distinguishes it from sibling tools like getTagType (single record) and createTag (write). The verb 'list' and resource 'tag types' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Use when' section explicitly stating when to use the tool ('enumerating the tag-type classifiers') and a 'See also' reference to getTagType for single records. While it does not explicitly say when not to use it, the context is sufficient for an agent to choose appropriately among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds valuable behavioral context beyond annotations: it explains the 'lean by default' behavior and how to restore full metadata with include_category_schema, details pagination (cursor-based with limit and page), and importantly describes a permission nuance (endpoint not in public Swagger, workaround for 403 errors). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but overly long. It includes a large table about the member category hierarchy and extensive permission notes, which while informative, could be condensed. The key purpose is front-loaded, but the additional detail makes it less concise. It is structured with sections, which helps, but overall it could be more succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema), the description is very complete. It explains the return format (status, total, pagination fields, records with all fields), the hierarchy, related tools, filtering and sorting rules, and edge cases like the permission workaround. It covers all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema descriptions. For example, it explains the effect of include_category_schema (lean vs full), references external rules for filter operators and pagination, and describes the default values and behavior. It provides context that helps the agent understand parameter interactions and nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List categories (professions) - Paginated enumeration of TOP-level member categories. Read-only.' It specifies the resource (top-level member categories) and the verb (list). It distinguishes from siblings by mentioning that for sub-categories, one should use listSubCategories, and lists related tools like getTopCategory and createTopCategory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use when: populating a category dropdown, generating a site map, or discovering the profession_id of an existing category before assigning members to it.' It also provides alternatives: 'For sub-categories under a specific top, use listSubCategories with a profession_id filter.' This clearly guides the agent on context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses pagination behavior (cursor-based, limit/page), filter/sort nuances (silent-drop detection, operator semantics, derived-field unfilterability), and the return object structure. These go well beyond the annotations, which already indicate read-only, idempotent, and non-destructive 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 well-structured with clear sections: purpose, use when, pagination, filter/sort, see also, and returns. It is concise and front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 7 optional parameters, the description covers pagination, filtering, sorting, and return structure. It mentions silent-drop and derived-field quirks. It could detail the record fields but states each record is the full resource object, which is acceptable given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions. The description adds value by explaining pagination cursor semantics, filter operator word forms, and silent-drop behavior. It references external rules but provides enough standalone context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists unsubscribe records, is paginated, and is read-only. It distinguishes itself from the single-record retrieval tool 'getUnsubscribe' via the 'See also' section. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' guidance for auditing, compliance, and campaign planning. It also points to the single-record alternative 'getUnsubscribe'. However, it does not explicitly exclude other list tools for different resources, but that is implicitly clear from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing partial-update semantics ('Fields omitted are untouched'), live data writes, and a specific refusal rule. It also details the return format and the meaning of `_admin_edit_url`, giving the agent full awareness of side effects and post-update actions. This aligns with the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence summary, a required-field note, behavioral rules, cross-references, and a return-value specification. Every sentence earns its place without redundancy. The formatting with bold headings and bullet-like separators improves scannability for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex update tool with 11 parameters and no output schema, the description covers all critical aspects: required field, partial updates, prerequisites, refusal conditions, return structure, and how to surface the admin link. Cross-references to shared 'Rule: Forms' are acceptable given the schema's thoroughness and the presence of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 82% of parameters with rich descriptions. The tool description adds cross-parameter context, such as the dependency between `form_action_type=redirect` and non-empty `form_target`, and the prerequisite to run `listFormFields` before certain changes. It also highlights `_clear_fields` as a special parameter, which is useful operational knowledge beyond the schema's per-field explanation.
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 opens with a specific verb-resource pair: 'Update an existing form record by ID.' It clearly distinguishes from sibling tools like createForm and deleteForm by emphasizing partial updates ('Fields omitted are untouched') and live writes. The 'See also' list reinforces its role as an update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool (updating existing forms) and provides actionable prerequisites, such as running `listFormFields` before flipping `form_action_type` to a public-facing value. It also names the wrapper-enforced refusal condition. While it doesn't explicitly say 'use this instead of X', the context and cross-references effectively differentiate it from create/delete operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation), destructiveHint=false (non-destructive), idempotentHint=true (idempotent), and openWorldHint=true (allows extra fields). The description aligns perfectly: it says 'update' and 'writes live data', confirms non-destructive behavior, and provides details on partial updates ('Fields omitted are untouched') and constraints (wrapper-enforced refusals). No contradictions; the description adds valuable behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured. It starts with a concise one-line summary, then organizes information into sections: required field, special case for renaming, external references, wrapper-enforced refusals, agent pre-checks, and see-also. Every sentence adds value, though some sections are dense. It balances detail with clarity, earning a high score for its context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 18 parameters, no output schema, and complexity, the description is comprehensive. It covers purpose, usage, behavioral constraints, parameter semantics, and related tools. It references external rules for deeper details. While it doesn't describe return values explicitly (common for update operations without output schema), it provides sufficient context for an agent to use the tool effectively. Slight overhead in length but justified by complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83% (high), so baseline is 3. The description adds significant meaning: for field_type, it warns about case sensitivity; for field_required, it explains forbidden combinations; for field_input_view, it clarifies not to use value 2; for _clear_fields, it details usage with examples. While the schema already describes most parameters, the description provides deeper behavioral context and cross-references, justifying a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'form field'. It specifies updating by ID and notes that omitted fields are untouched, distinguishing it from creation or deletion. The phrase 'Writes live data' confirms it's a live operation. This is specific and distinct from siblings like createFormField, deleteFormField, and listFormFields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes the required parameter 'field_id' and provides extensive guidance on when to use the tool, including special cases like renaming fields on a specific form, referencing external rules for field anatomy and validators, detailing wrapper-enforced refusals, and listing agent pre-checks. It also lists related tools (createFormField, deleteFormField, listFormFields) as alternatives, offering clear context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that fields omitted are untouched, writes live data, and returns the full updated record. It also details enum behavior and BD's silent acceptance of out-of-range values, adding context beyond annotations. However, it does not explicitly mention idempotency or non-destructiveness, though implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (main purpose, use when, required, enums, see also, returns). Every sentence provides value, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count (4) and no output schema, the description covers enum details, return format, special parameter behavior, and references sibling tools. It is comprehensive enough for an agent to use correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning to parameters: explains enum values for lead_status (non-sequential, accepted silently), details the _clear_fields parameter behavior, and notes that omitted fields are untouched. With 50% schema coverage, the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and resource 'lead match', and distinguishes from sibling tools (createLeadMatch, deleteLeadMatch) in the 'See also' section. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use ('recording a member's response...' or 'adjusting lead_points/match_price'), requires 'match_id', and references alternative tools for creating and deleting. This provides clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutation (readOnlyHint false) and idempotent hint. The description adds: 'Fields omitted are untouched' (partial update) and 'Writes live data'. No contradiction. However, it could further detail idempotent behavior or side effects beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-structured sentences with bold headings. The most critical info (purpose, use cases, required param, returns) is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description specifies the return format ({ status, message }). It covers necessary context: update by ID, partial update, live data, and required parameter. The 6-parameter input schema is adequately addressed for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (3 of 6 parameters have descriptions). The description adds value by explaining that omitted fields are untouched and gives concrete examples for menu_link, menu_order, menu_active. It does not detail _clear_fields or menu_order/menu_active schemas, but the examples compensate partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a menu item' and distinguishes from siblings by explicitly mentioning createMenuItem and deleteMenuItem as alternatives. It specifies the resource (menuitem) and operation (update by ID), leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: renaming, re-linking, reordering, hiding. Also mentions required parameter (menu_item_id) and references related tools (createMenuItem, deleteMenuItem). This gives clear guidance on when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses imperative behavior (writes live data) and field omission semantics. Notes limitation on re-importing. Annotations provide idempotentHint=true; description doesn't confirm but doesn't contradict. Adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (intro, use when, required, cannot, see also, returns). Every sentence adds value; no redundancy. Efficient for agent parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides return format description, parameter roles, and usage constraints. No output schema, but description covers expected output. With annotations and sibling context, the tool is fully specified.
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?
Although schema coverage is low (25%), the description explains purpose of title and order fields, and clarifies _clear_fields usage. It compensates by clarifying field update behavior and stating that omitted fields are untouched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an album photo by ID, specifying it writes live data and fields omitted are untouched. It distinguishes from sibling tools like createMultiImagePostPhoto and deleteMultiImagePostPhoto.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (reordering, renaming) and provides required parameter photo_id. Includes limitations (cannot re-import failed image) and alternatives (delete then update group). References sibling tools for reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it writes live data, fields omitted are untouched, and provides a critical caveat about filename renaming orphaning web pages. It also states the return format. This adds valuable context beyond the annotations, which already mark it as read-only false and idempotent true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (Use when, Required, Parameter notes, etc.), but it is somewhat lengthy, including tangential information about how members are classified and a note about tool naming. Every part is useful, but slight trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers update behavior, return format, related tools, and important caveats. It includes a sub-sub-category explanation. However, it does not detail all 10 parameters individually (e.g., sort_order, keywords from schema, name). Overall, it provides sufficient context for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for several parameters: profession_id (re-parenting), master_id (sub-sub-category nesting), filename (rename caveat), and lead_price (per-service pricing). However, it omits explanations for sort_order and name, and schema coverage is only 40%. Still, it compensates well for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a SUB-level member category by service_id, with specific actions like renaming, re-parenting, and adjusting lead_price. It also distinguishes itself from create and delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use when:' section with explicit scenarios, a 'See also:' pointing to createSubCategory and deleteSubCategory, and a note clarifying that there is no createProfession or createService tool, guiding users to correct alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by detailing cache refresh behavior, response format, side effects of renaming, and that fields omitted are untouched. Annotations provide little behavioral context, so the description is critical.
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 long but well-structured with sections, bolding, and bullet points. It front-loads the core action and avoids unnecessary repetition, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, no output schema), the description covers primary use, caveats, and return format. It references external rules and 'listWidgets' for full field list, which is acceptable but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, and the description adds context for common edits and renaming. However, several parameters already have detailed schema descriptions, so the description complements rather than compensates fully.
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 starts with 'Update an existing widget by `widget_id`', clearly stating the verb and resource. It distinguishes from siblings by referencing 'createWidget' and 'deleteWidget'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use when: editing widget HTML, CSS, JS, or metadata.' It also warns against accidentally renaming and points to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Warns that BD does not enforce uniqueness on email_name, describes enum side-effects, optional fields at create, and HTML wrapping behavior. No contradiction with annotations (readOnlyHint=false). Adds substantial behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (use when, pre-check, enums, interactions, see also). Slightly verbose but justified by complexity (13 params). Front-loaded with purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers most aspects: required params, enums, pre-flight check. Missing return value description and error conditions. With no output schema, some information gap, but still comprehensive overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains enum values (e.g., notemplate modes, category_id restrictions), parameter interactions (tokens in subject/body, HTML support), and naming rules for email_name. Schema coverage 62%, description compensates richly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States verb+resource: 'Create an email template - Create a new emailtemplate record.' Distinguishes from siblings by noting rarity and referencing updateEmailTemplate as alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: adding a new transactional/marketing template.' Provides a detailed pre-check procedure to avoid duplicates, recommends updateEmailTemplate if name is taken, and includes 'See also: updateEmailTemplate' for modification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly=false, openWorld=true), the description discloses that the tool 'Writes live data', flags BD's lack of uniqueness enforcement on form_name causing ambiguous shortcodes, and reveals a wrapper-enforced refusal when form_action_type=redirect with empty form_target. These are actionable behavioral constraints not present in structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, using bolded required fields, rule references, and a clear return contract. Each section contributes to parameter constraints or usage context, though the heavy reliance on external 'Rule: Forms' references and the sheer length prevent a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters and no output schema, the description fully compensates by defining the return shape ({status, message, _admin_edit_url}) and instructing the agent to surface _admin_edit_url to the user. It also covers prerequisites, exclusions, and wrapper enforcement, making the tool's behavior predictable in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 15 parameters. The description adds extra semantic value by highlighting form_name uniqueness pre-checks, form_target's conditional requirement based on wrapper rules, and form_table's clone-vs-create guidance. This exceeds the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Create a form - Create a new form record') and immediately distinguishes itself from the later step 'Add fields afterward via createFormField'. It also lists sibling tools (updateForm, createFormField, listFormFields) in a 'See also' section, making differentiation clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance: it instructs agents to add fields via createFormField, warns against free-creating leads and users_data forms ('never free-create from scratch'), and directs consultation of 'Rule: Forms § Form classes before picking form_table'. It also names alternatives via 'See also'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are readOnlyHint=false (write operation) and destructiveHint=false (not destructive). The description adds: 'Writes live data', default silent behavior (no notifications unless flags), no automatic member routing without auto_match or matchLead, response includes lead_id and token, and operational rules from support article. This goes well beyond annotations, providing essential 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?
Description is long but well-structured with headings, bullet points, and clear sections. It front-loads the core purpose and usage, then dives into details. Every sentence adds value—no fluff. The structure aids readability for an AI agent parsing instructions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, 2 enums, no output schema, and complex workflow (notifications, matching, member overrides), the description is remarkably complete. It covers operational rules, parameter interactions, response fields (lead_id, token), recommends sibling tools (listTopCategories, updateLead, matchLead), and even references a support article. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet description adds substantial meaning: explains default values (0 for flags), parameter interactions (auto_match and users_to_match combinations), and patterns (e.g., 'Typically paired with auto_match=1 AND send_lead_email_notification=1'). It clarifies that required fields must be supplied together. Description compensates fully despite schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with 'Create a lead - Create a new lead record. Writes live data.' which clearly states the verb (create) and resource (lead). It distinguishes from siblings like updateLead and createLeadMatch by explaining the default silent behavior and the optional matching workflow. 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly states when to use: 'importing leads from an external form, CSV, or web-scrape.' It explains default silent mode, when to pass flags (send_lead_email_notification, auto_match), and references sibling tool matchLead. It does not explicitly say when NOT to use, but context is clear enough. A slight improvement would be an explicit contraindication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behaviors: non-idempotent nature, potential for infinite loops, and required pre-checks. Adds context beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) by explaining why these checks are necessary and what happens if not done.
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?
Long but well-structured with sections, bold headers, and numbered steps. Front-loaded with purpose and key usage. Every sentence adds value, though could be slightly more concise. The pre-check detail is justified by the tool's risk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (dangerous redirects, no output schema, many siblings), the description covers purpose, usage, pre-checks, parameter details, and alternatives. It is fully complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds meaning by clarifying that old_filename and new_filename are relative paths, explaining db_id's purpose, and noting that id is legacy. Also explains that type is wrapper-managed, which is not in schema but relevant. Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a new 301 redirect rule' and specifies it's for preserving SEO after URL changes like slug renames. Distinguishes from siblings by naming updateRedirect and listRedirects, and explains when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (API-triggered changes, not admin-triggered), what to avoid (duplicate old_filename), and detailed pre-check steps (idempotent skip, conflict detection, loop prevention). Also mentions see also updateRedirect.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that added_by is wrapper-managed, duplicate tag_name is silently accepted, and group_tag_id FK is not enforced, providing critical behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and front-loaded purpose, but slightly verbose; every sentence is informative, though some redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, edge cases, duplicate handling, return format, and references to sibling tools, fully compensating for lack of output schema.
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?
Even with only 50% schema coverage, the description adds meaning by explaining tag_name as 'visible label' and detailing group_tag_id constraints and interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'tag', distinguishes from siblings like updateTag and listTags, and specifies it writes live data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: adding a new tag', requires group existence from listTagGroups, and recommends a pre-check pattern for duplicate detection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false). The description adds critical behavioral details: immediate live data visibility, wrapper auto-suffix on collision, and return format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings and logical flow, starting with purpose and usage. However, it is quite lengthy (multiple paragraphs). Every section earns its place, but could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 params, no output schema, taxonomy system), the description is exceptionally complete. It covers pre-checks, wrapper behavior, full workflow, sub-category creation, and relationship to other tools. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying filename as URL-slug, explaining desc is not SEO, and grouping optional parameters. It also highlights the pre-check requirement for filename uniqueness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new top-level member category, using specific verbs and resources. It distinguishes itself from siblings like createSubCategory, listTopCategories, and getTopCategory by explaining the role in the 3-tier taxonomy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use ('before members exist') and when to skip (pass profession_name to createUser). Provides alternatives, a pre-check procedure, and a full workflow example. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description reinforces this with 'Permanently delete', 'cannot be undone', 'confirm intent', and 'no soft-delete'. It also explains the need to delete children first and outlines the return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, usage, required parameter, alternative, warnings, and return format. It is slightly verbose but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, but the description provides the return format. It addresses relationships with sibling tools, irreversibility, and the need to handle child records. With one parameter, it is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter (group_id) and 0% schema description coverage, the description adds that it is required and implies its role as the ID of the album group. While not elaborate, the meaning is clear from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete', the resource 'album group / portfoliogroup record', and the permanent nature of the action. It distinguishes itself from siblings like deleteMultiImagePostPhoto and updateMultiImagePost.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('removing the entire album'), provides a recommended sequence (delete child photos first), warns about orphan rows, and mentions an alternative (updateMultiImagePost for modifications).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive nature, irreversibility, no soft-delete via API, and need for intent confirmation. Aligns with annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is detailed but each sentence adds value. Front-loaded with purpose and guidelines. Could be slightly trimmed but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return values, parameter interactions, and alternatives. Given no output schema, it provides enough context for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning to both parameters: user_id as required, delete_images as optional with explanation of its effect. Schema had 50% coverage (delete_images described), so description compensates and adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool permanently deletes a user by ID. Distinguishes from siblings like updateUser for reversible removal, and from other delete tools by specifying it's for user records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists when to use (GDPR, cleanup, duplicates) and when not to (prefer updateUser with active=3 for reversible removal). Also mentions optional image deletion and provides alternative tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds critical behavioral context: the compound identity risk, cross-table destruction potential, the fact that BD does not cascade-delete, and the exact return format. This goes well beyond annotations with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear summary, hard rule, use cases, workflow, see also, and return value. It is front-loaded with the purpose. However, it is somewhat verbose; with multiple paragraphs, some sentences could be streamlined without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the lack of output schema, the description explicitly states the return format. It covers purpose, risks, usage pattern, alternatives, and prerequisites. For a destructive tool with cross-table implications, this is comprehensive and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 67% of parameters with descriptions, but the description reinforces the compound identity of (database, database_id) and explains why both are required to prevent cross-table destruction. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Delete a metadata record - Permanently delete a users_meta record by meta_id.' It specifies the resource (users_meta) and action (delete), and distinguishes from siblings by naming the specific table and emphasizing the compound identity requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases are given: 'Use when: removing a specific metadata row, OR cleaning up orphan meta rows after a parent record is deleted.' It warns against loop-deleting by database_id alone and provides a safe cleanup workflow. It also references alternatives: updateUserMeta and listUserMeta.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint: true), the description details destructive implications, automatic cascade for data_category, orphan cleanup requirements, and post-deletion workflow. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and code formatting. Front-loaded with core purpose. Although verbose, each sentence serves a purpose given the tool's destructive nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Includes return value, side effects, pre/post conditions, references to related tools, and warnings for a complete understanding. No output schema, but description compensates fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% with a basic description for seo_id. Description adds 'Required: seo_id' and contextual usage throughout, enhancing semantics beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a page - Permanently delete a web page by seo_id', specifying the action, resource, and key differentiators like destructive nature and irreversibility. It also distinguishes from siblings by referencing updateWebPage and createRedirect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: permanently removing a page.' Provides prerequisites (confirm with user, consider redirect), warns against common mistakes (looping by database_id), and lists alternatives (updateWebPage). Comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds valuable behavioral details: 20 parallel internal calls, rate limit, caching advice, fallback defaults, and response shape with usage guidance. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is lengthy but well-structured, front-loading purpose and usage. Every sentence adds value, though some technical details could be condensed. Still earns a 4 for being informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description provides comprehensive detail on response shape, usage guidance, and edge cases (empty slots, auth, rate limit). Fully equips the agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (0 params, schema coverage 100%), so baseline score is 4. Description mentions 'No args.' which is sufficient; no further parameter info needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves the site's brand kit (colors and fonts) for design decisions. It specifies use cases like building widgets, webpages, etc., and distinguishes itself from siblings by its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call 'ONCE at the start of any design-related task' and notes 'Safe to call anytime.' Provides clear context for when to use the tool, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, etc.), description reinforces read-only, details lean-by-default keep-list, specifies exactly which optional bundles restore which fields, notes EAV-routed fields not merged, and explains return format. Adds substantial 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear sections, front-loaded purpose. Slightly verbose in the keep-list enumeration but each part serves a purpose. No fluff, efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description fully explains return format, lean-by-default fields, opt-in bundles, and a known limitation (EAV not merged). Complete context for using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema coverage, description compensates by explaining the lean-by-default pattern, clarifying the purpose of each include_* flag in context, and emphasizing subscription_id is required. Adds meaning beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Get a single membership plan' and 'Fetch a single membership-plan record. Read-only.' Differentiates from sibling `listMembershipPlans` for enumeration, giving a specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use when: fetching one plan's config' and references sibling `listMembershipPlans` for enumeration. Positive guidance is clear and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds critical info about lean default behavior (strips SEO metadata), how to opt-in (include_category_schema=1), and return format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Core purpose and usage are front-loaded in first sentences. However, additional paragraphs about member classification and sub-sub-categories, while informative, extend length. Could be trimmed without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, return format, lean behavior, and when to use. Provides relevant domain context about classifications. No output schema but return format is described. Complete for a read tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only include_category_schema has description). Description compensates by explaining what each parameter does: service_id is path, include_category_schema restores metadata. Adds meaning beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get a single service - Fetch a single SUB-level member category (service) by service_id.' Specifies verb and resource, and distinguishes from sibling tools like listSubCategories and getTopCategory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' guidance and 'See also' section naming alternative tools and their purposes. Tells agent to use after discovering via listSubCategories, and contrasts with getTopCategory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds substantial context beyond annotations, including the lean-by-default keep-list, behavior of include flags, return format, filename regeneration, and payment method detection logic. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings, bullet points, and clear sections (purpose, usage, params, return, notes). While lengthy, every sentence serves a purpose. Some redundancy (e.g., 'Get a single member/user' repeated) could be trimmed, but overall structure is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters and no output schema, the description is extremely thorough: covers return format, success/error behavior (empty array/404), special fields (card_info), filename usage and regeneration caveat, and references to siblings. It leaves no important aspect unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (92%), so baseline 3. The description adds significant value by explaining the lean-by-default keep-list, the purpose of each include flag (e.g., 'include_extras' bundle content), and the semantics of 'card_info'. However, the schema already documents most parameters, so the description supplements rather than replaces.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get a single member/user - Fetch a single user record', clearly identifying the tool's action and target. It differentiates from siblings like listUsers (enumerate many) and searchUsers (keyword search), providing clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use when: you already have the user_id...' and contrasts with alternatives: 'For lookups by email or other field, use listUsers with property/property_value.' It also includes a caveat about re-fetching filename after updateUser.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld. Description adds that it returns status/message structure, with empty/404 when not found, which is additional useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is clear and well-structured with 'Use when' and return format. Slightly verbose (code block), but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description explains return format and use case context (site-specific custom fields). Fully covers what an agent needs.
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?
No parameters; baseline 4 applies. No additional param info needed.
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?
Describes retrieving user field definitions with labels and required flags. Distinguishes from siblings like getPostTypeCustomFields by specifying 'user records' and noting custom fields vary per site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: building dynamic forms or importers - you need to discover which fields exist on the User record on THIS specific site' and also mentions validating import-CSV headers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds details about pagination (cursor-based), filtering (including silent-drop on wrong property names), sorting, and response format. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Pagination, Filter/sort, See also, Returns). It is detailed but not overly verbose, though slightly lengthy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers usage context, pagination behavior, filtering operators, and response format. It provides necessary context for a tool with 7 optional parameters and complex filtering, and references external rules for further detail. No output schema, but return format is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters relate to the tool's purpose (e.g., 'use the data_id values as data_type parameters'), references external rules for pagination and filtering, and clarifies compound filter semantics. However, it does not add new parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all data types configured on this BD site' and explains that data_id values are used as data_type parameters for creating posts or portfolio groups. It distinguishes itself from the sibling 'getDataType' which retrieves a single record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: discovering the valid data_type values on the site. Used as a prerequisite lookup when creating posts or portfolio groups that need a data_type foreign-key value.' It also suggests 'getDataType' as an alternative for single record lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly labels the tool as 'Read-only' and describes pagination ('cursor-based'), return structure, and merging behavior with site records and platform defaults. It references rules for filter operators and pagination semantics. This adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: 'Use when:', 'Pagination:', 'Filter/sort:', 'See also:', 'Returns:'. It is front-loaded with purpose. While slightly lengthy, it is concise given the complexity of the 9 parameters and the need to cover filtering, pagination, and default merging.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description provides a detailed return structure and explains that records include merged defaults. It covers all 9 parameters with additional context and references rules for detailed filter operators and pagination. This gives a comprehensive understanding of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds extra meaning for parameters like property (explains multi-condition AND with parallel arrays), include_meta (use case for editing validators), and include_view_flags (visibility flags). It also references external rules for filters and forms, providing more context than schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List form fields - Paginated enumeration of formfield records. Read-only.' The verb 'list' and resource 'form fields' are specific. It distinguishes from siblings like getFormField (single record) by explicitly mentioning it in 'See also: getFormField'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Use when: listing fields on a form.' and provides specific filtering guidance (filter by form_name, joins by text slug not ID). It also mentions 'See also: getFormField' as an alternative for single records, helping the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context by stating 'Read-only', explaining pagination and filter/sort behavior as 'standard', and detailing the return format with fields like rel_id, user_id, service_id, etc. It also describes the underlying table (rel_services) and how it fits into the broader classification system, which helps the agent understand 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 lengthy but well-structured with clear sections: purpose, use-cases, pagination, return format, business context. Every sentence adds value, though some tangential details about sub-sub-categories and table mapping could be streamlined. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema), the description provides a complete picture: it explains the return format with all fields, pagination, filtering options, and the business context of how member classification works (profession_id, services CSV, rel_services). It also clarifies relationships with sibling tools and internal table mappings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by giving example use cases for filtering: 'Filter by user_id to see one member's links, service_id to see everyone offering that service.' It also warns about wrong property names silently returning empty, which is beyond the schema. This justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List user-service relationships - Paginated enumeration of MEMBER ↔ SUB CATEGORY links. Read-only.' It specifies the verb (list), resource (membership links), and scope (paginated, read-only). It distinguishes from sibling tools like getMemberSubCategoryLink (single item) by indicating this is a list endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when-to-use scenarios: 'Use when: auditing per-service-link metadata... For simpler checks, the users_data.services CSV is cheaper.' It also contrasts with updateUser for simpler cases and references sibling tools like getMemberSubCategoryLink, createMemberSubCategoryLink, listSubCategories. This gives clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: lean-by-default keep-list, marketplace fields restoration via include_marketplace, cursor-based pagination, filter operators, silent-drop detection, and derived-field unfilterability. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, bold keywords, and bullet points. It front-loads the main purpose. While somewhat long, every sentence provides useful information for a complex tool. Minor verbosity but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, pagination, filters, and no output schema, the description compensates by detailing the return shape (status, total, current_page, etc.), lean response, filtering options, and references to rules. It is highly complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the keep-list columns, the effect of include_marketplace, pagination details, and filter operators (including compound filters). This goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List album photos - Paginated enumeration of portfoliophoto records. Read-only.' This clearly specifies the action (list), resource (album photos/portfolio photo records), and pagination. It also distinguishes from sibling tools like getMultiImagePostPhoto and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: fetching all photos within a multi-image post - always pass group_id to filter.' and provides alternatives: 'For a single photo by ID use getMultiImagePostPhoto. For image-dedup: property=original_image_url...' It also includes a 'See also' section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explains default lean behavior, opt-in for full schema, cursor-based pagination, and hierarchy visibility. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint: false). It adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long and includes additional background (member classification, internal tables) that could be separated into rules or notes. While well-structured with bold headers and sections, it exceeds conciseness expectations for a single tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description thoroughly explains the response shape ('{ status: "success", total, ..., message: [...records] }') and record fields. It also covers pagination, filtering, sorting, permissions, and relationships with other tools, making the context fully actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds valuable context: each parameter's effect (e.g., silent empty returns for wrong filter columns), compound filtering with parallel arrays, and the include_category_schema parameter's impact on response fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: paginated enumeration of sub-categories. It distinguishes from siblings like getSubCategory (single by ID) and listTopCategories (parents). The verb 'list' and resource 'services (sub-categories)' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'always filter by profession_id to scope to one Top Category' to avoid noise. Also advises against using API key permissions meant for other endpoints. Mentions alternative tools under 'See also'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral context: lean-by-default keep-list, performance considerations (10-30KB per row), opt-in flags, pagination behavior, and filter/sort references. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and bullet points. Front-loaded with purpose. Some redundancy (e.g., 'Read-only' appears twice), but overall efficient for the complexity. Slightly verbose but justified by the tool's richness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explicitly states the return format: '{ status: 'success', total, ..., message: [...records] }'. Details the keep-list fields and extras. Covers pagination, filtering, sorting, and usage guidance comprehensively. Very complete for a complex listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all 10 parameters (100% coverage). Description adds significant meaning by explaining the 'lean-by-default' pattern, what each include_* flag restores, and the pagination cursor mechanism. This exceeds baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'List pages (list_seo) - Paginated enumeration of web pages (list_seo records). Read-only.' and then lists the types of pages included. It clearly distinguishes from sibling tools like getWebPage (single by ID) and mentions create/update versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: listing all site pages. Filter by seo_type to scope. For one page by seo_id use getWebPage.' Also advises when to opt into include_* flags (e.g., before updateWebPage edits).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains read-only nature (redundant with annotations but adds context), the lean-by-default keep-list, pagination cursor/cap/stop, silent-drop detection, derived-field unfilterability, and default-merge model. It significantly supplements the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with sections, bullet points, and a table. It front-loads the core purpose and then provides necessary details. Minor redundancy but overall efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: pagination, filtering, default-value merging, the return format, and a full table of widget object fields. No output schema exists, so the description compensates thoroughly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context: 'include_code=1 to restore widget_data/style/javascript', 'Useful filter: widget_viewport=front', and detailed filter operator descriptions. It provides value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List widgets - Paginated enumeration of widget records.' It specifies that it's for discovering reusable components and distinguishes from related tools like getWidget, createWidget, and updateWidget.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when: discovering the reusable HTML/CSS/JS components available for embedding...' and provides alternatives: 'For fetching one specific widget by ID use getWidget.' Also includes filter/sort tips and references to rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses PATCH semantics, the warning about city_filename edits breaking URLs requiring redirect creation, and the _clear_fields mechanism. Annotations are consistent and description adds valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, but slightly verbose. Each sentence adds value, though some details could be more succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavioral notes, return format, and parameter details. With annotations providing safety info, this is fully complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema for locaiton_id (typo), city_filename (URL slug), and _clear_fields (detailed explanation). However, schema coverage is 50% and some parameters like city_ln and state_sn rely solely on schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing city row, with specific uses like correcting typos or reassigning IDs. It distinguishes from creating a new city, which is not via API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use (corrections, reassignments) and when not to (new city). Provides clear alternatives and prerequisites like required locaiton_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses live data writing, filename rename caveat (orphaning pages, rejection), and that fields omitted are untouched. No contradiction with annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false). Adds critical behavioral context beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and front-loaded key points. Some repetition in explaining classification and subcategories could be condensed, but each part adds value. Efficient use of space given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format, required fields, caveats, parameter details, and even background on member classification. No output schema, but return format is specified. Thorough for a 10-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning for key parameters (filename with URL slug and SEO impact, desc as internal label, keywords as fuzzy synonyms, _clear_fields with clearing rules). For parameters without schema descriptions (name, icon, etc.), no extra detail, but overall compensation is high. Schema coverage 50% is adequately supplemented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (update), resource (top-level member category), and key behavior (fields omitted are untouched, writes live data). It distinguishes from sibling tools like createTopCategory and deleteTopCategory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' scenarios, required parameter (profession_id), caveats about renaming filename and orphaning pages, and references to related tools. Clear guidance on when to use and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses writes live data, identity rule preventing cross-table corruption, and that fields omitted are untouched. Covers _clear_fields behavior. Annotations align (idempotentHint=true, openWorldHint=true). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bold emphasis. Some redundancy in identity rule, but necessary for clarity. Front-loaded purpose. Slightly long but justified by complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers prerequisites, alternatives, workflow, required params, identity rule, clearing fields, return format, and error handling. No output schema but describes return. Thorough and self-contained.
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?
Description adds significant meaning beyond schema: explains identity pair requirement, confirms database/database_id must match existing row, details _clear_fields usage. Schema coverage 60% but description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update a metadata record' and specifies updating the 'value' field by 'meta_id'. It distinguishes from siblings like createUserMeta, deleteUserMeta, and updateWebPage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (existing meta from createUserMeta) and when-not (list_seo fields via updateWebPage). Includes a step-by-step workflow and identity rule, effectively guiding the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only, not destructive, idempotent, and open-world. The description adds substantial behavioral context beyond these: automatic cache refresh, PATCH semantics (omitted fields untouched), hero bundle auto-fill on transition, EAV-routing behavior, and the fact that `seo_type` changes are destructive. It also documents misnamed fields (e.g., `show_form` for noindex). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long (multiple paragraphs). While comprehensive, it includes repeated details (e.g., hero bundle defaults mentioned in both the `enable_hero_section` field description and the dedicated hero section). The structure front-loads the purpose but then dives into deep details. For a tool with 64 parameters, some length is justified, but it could be more concise and better organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (64 parameters, no output schema), the description is remarkably complete. It covers edge cases (e.g., homepage hero benign, `profile_search_results` slug requirements, double-render trap for H1/H2), common edits, misnamed fields, asset field routing, EAV routing, and even post-deletion orphan cleanup. It also provides specific guidance for `seo_type` changes and hero transitions. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial meaning beyond field descriptions. It explains misnamed fields (e.g., `content_footer` is an access gate, not HTML), template tokens, asset field routing rules, hero bundle defaults, and EAV auto-routing. For fields like `enable_hero_section`, it details the auto-fill behavior and required companion fields. This dramatically enhances comprehension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update'), resource ('an existing `list_seo` page'), and identifier (`seo_id`). It also differentiates from sibling tools by mentioning PATCH semantics and explicitly referencing `createWebPage`, `deleteWebPage`, and `createRedirect` in the 'See also' section. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive guidance on when to use this tool versus alternatives. It includes a 'Disambiguation' section that warns about resource ambiguity when users refer to pages by title, and directs to a rule for clarifying. It also explicitly states conditions for using `createRedirect` (slug change), `deleteWebPage` (with orphan cleanup), and `refreshSiteCache` (when cache refresh fails). This is exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the system does NOT enforce uniqueness on category_name, leading to potential corruption. It details the required pre-check and consequences of duplicates. This adds significant behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Required, Pre-check, Enums, See also). It is slightly verbose but every sentence provides value. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully covers input parameters, behavioral requirements (duplicate checking), and edge cases (reuse, ask, alternate name). References sibling tool updateDataType. Complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning: it lists required parameters, explains enum values for category_active and limit_available, and provides pre-check context that enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Create a data type - Define a new content-type template.' It specifies that this is for new post types and that most sites are pre-configured, distinguishing it from related tools like updateDataType.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Only do this when the user explicitly wants a new post type.' Provides a pre-check to avoid duplicates, with clear steps and alternatives (reuse via updateDataType, ask user, pick alternate name). Includes when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool writes live data (matching annotations), warns about duplicate links not being enforced, and explains the impact on the public profile. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with sections (summary, usage, pre-check, parameters, see also). It is front-loaded with purpose, though some tangential context at the end could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers when to use, duplicate handling, parameter details, side effects, related tools, and even the broader classification system. No output schema exists, but return format is mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite low schema coverage (20%), the description explains each parameter's purpose, meaning, and source (e.g., user_id from listUsers), fully compensating for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool creates a link between a member and a subcategory with optional metadata. It contrasts with the simpler updateUser approach, making its purpose distinct among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool (when per-link metadata needed) versus updateUser (plain tagging). It provides a pre-check pattern and alternative actions if a duplicate exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing critical behaviors: 'Writes live data,' 'HTTP 200 does NOT mean every photo imported,' duplicate group_name causes URL collisions, and auto_image_import fetches externals into site storage. It also describes post-create verification steps, silent-failure rows, and the instruction 'Do NOT delete and recreate the album.' No contradiction with annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false).
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 long but well-structured with bold section headers (Use when, Required, Pre-check, Parameter interactions, Post-create verification, etc.) and a clear data_type mapping table. It is front-loaded with the core purpose and use-when guidance; while lengthy, the detail is necessary for a complex creation tool with many failure modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format ('{ status: "success", message: {...createdRecord} }'), post-create verification via listMultiImagePostPhotos, the consequence of choosing the wrong endpoint, and the lack of post_category for multi-image posts. Despite no output schema, the description fully prepares the agent for the create flow, verification, and failure recovery.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds substantial meaning beyond the schema: group_name uniqueness and collision risk, post_image must be landscape and end in .jpg/.jpeg/.png with no query strings, data_type must be 4 and read from listPostTypes/getPostType, auto_image_import=1 needed for external URLs, and group_status meanings including 3=Pending Approval. These details are essential for correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create an album group - Create a new portfoliogroup record. Writes live data,' giving a specific verb and resource. It further distinguishes from siblings by explicitly stating 'data_type=4 belongs here; 9/20 belongs in createSingleImagePost,' and explains the tool's role for multi-image post types like albums and galleries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when:' conditions (photo album, gallery, product listing, or any post type with data_type=4), and names alternatives: 'createSingleImagePost' for data_type 9/20, and 'createMultiImagePostPhoto' for already-hosted URLs only. It also gives a full data_type-to-endpoint mapping table and warns against using the wrong endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses non-obvious side effects: BD does NOT enforce title uniqueness, auto-generates a filename causing URL collisions, may accept rows from wrong endpoints yet fail to render, and stores certain fields in users_meta rather than data_posts. It also documents the duplicate-prevention pre-check workflow and warns against paginating unfiltered lists. This goes well beyond the minimal annotation set (readOnly=false, openWorld=true, idempotent=false, destructive=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long but well-structured with bold headers, tables, and front-loaded purpose/usage. Some redundancy exists (the data_type table repeats schema info), but the density of critical warnings justifies most length. It earns a 4 because it is thorough yet slightly repetitive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, alternatives, failure modes, duplicate prevention, parameter interactions, endpoint selection, category selection, and response contents (post_id/post_token). Even warns about getSingleImagePostFields returning a generic super-union list for invalid form_name. With no output schema and 29 parameters, this is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 90% schema coverage, the description adds significant interaction knowledge: post_promo back-fills post_price, post_category values must be passed verbatim because BD doesn't trim whitespace, post_start_date/post_expire_date use event-local wall-clock vs site timezone, and post_url/post_venue are stored in users_meta. It also warns against calling listDataTypes and clarifies data_type is a classification, not a per-site FK.
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 opens with 'Create a post - Create a new post record. Writes live data.' and enumerates concrete post types (blog article, event, job listing, coupon). It explicitly contrasts with createMultiImagePost via the data_type family table and points to updateSingleImagePost for modifications, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a dedicated 'Use when' section naming specific post types, and explicitly says 'If data_type=4 on the post type, use createMultiImagePost instead.' It includes a full endpoint-selection table and intent-based routing examples for 'make a blog post' vs 'make a photo album', leaving no doubt about alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false). The description adds significant behavioral context: it writes live data, warns about duplicate name confusion, explains backend encryption behavior ('do NOT pre-encrypt'), and notes that the format of smart_list_query_params depends on smart_list_type. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and flows logically through use case, requirements, pre-check, parameter details, and cross-reference. However, it is verbose—the pre-check block contains multi-sentence instructions that could be condensed without losing value. Slightly over-communicates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and lightweight annotations, the description covers everything an agent needs: purpose, required fields, parameter interactions, duplicate handling, and an alternative tool. It is fully self-contained and leaves no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 3 of 5 parameters (60%) but descriptions are sparse. The description extensively explains the conditional format of smart_list_query_params based on smart_list_type, the 'NA' sentinel for no filters, and the encryption warning. It also identifies smart_list_created_by as an admin user ID. This adds critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Create a smart list - Create a new smartlist record. Writes live data.' It distinguishes from sibling tools like updateSmartList by explaining the creation context and noting alternative uses. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when: programmatically saving a filter configuration for later reuse.' It provides a detailed pre-check for name uniqueness and instructs what to do if a duplicate exists, including rerouting to updateSmartList. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool writes live data, warns about lack of uniqueness constraints causing duplicates, details the triple uniqueness check and filter-find pattern, and explains tag_type_id mapping via listTagTypes. This goes beyond annotations, which only provide 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?
Well-organized with sections (Use when, Required, Pre-check, Parameter interactions, See also, tag_type_id mapping). Every sentence adds value, and the structure is front-loaded with purpose. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Very thorough in usage, pre-checks, and parameter details, but does not explicitly describe the return value (e.g., created relationship ID or success). Given no output schema, a brief mention of output would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains tag_id is a stringified integer, clarifies added_by is required, and provides detailed mapping for object_id and tag_type_id with examples. Schema coverage is high but description enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a tag relationship - Create a new tagrelationship record.' and distinguishes from siblings like createTag and updateTagRelationship, explicitly noting when to use this tool versus updateUser for member tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: attaching an existing tag to a record' and provides an alternative for members using updateUser. Also recommends pre-check for duplicates and references updateTagRelationship for modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description details behavioral traits such as writes live data, silent welcome email default, email uniqueness handling, field validation quirks (URL format, token length), and parameter interactions (auto_image_import delay, auto_geocode requirement).
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 long but well-structured with clear headings (Required, Use when, Enums, Prerequisites, etc.) and front-loaded with the core purpose. Some redundancy exists (e.g., repeated URL format notes), but the structure makes it scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 54 parameters, no output schema, and high complexity, the description covers prerequisites, parameter interactions, edge cases (duplicate emails, silent failures), return format, and even data sourcing guidelines. It is exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite high schema coverage (83%), the description adds substantial meaning: enum explanations (active states, listing_type default/case sensitivity), format requirements (services comma-separated, bare image URLs, YYYYMMDDHHmmss timestamps), and asymmetries (profession_name create vs update).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new member/user' and provides specific use cases (CSV imports, scraped listings, Zapier automations, admin test accounts), clearly distinguishing this tool from siblings like createLead or createForm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section and 'See also' reference (updateUser, deleteUser) provide explicit guidance on when to use this tool versus alternatives, along with prerequisites and idempotent patterns for email duplication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no behavioral hints (readOnlyHint=false, destructiveHint=false, etc.), so the description carries full burden. It fully discloses: writes live data, automatic cache refresh, thin-content warnings, asset field routing, hidden behaviors (e.g., breadcrumb auto-generation, hero readability autofill). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is very long, it is well-structured with sections, bullet points, and bold headings. It front-loads a summary. Given the tool's complexity (62 parameters, many edge cases), the length is justified. However, it could be slightly more concise without losing essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: creation workflow, field dependencies, error handling (auto_cache_refreshed), return value structure, and integration with other tools. Even without an output schema, the description fully explains response fields. Addresses edge cases like filename uniqueness, EAV routing, and thin-content warnings. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds extensive context beyond the schema. For example, explains the actual meaning of misnamed fields like content_footer and form_name, details hero section parameter interactions, and provides enum value semantics. This extra context is crucial for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Create a page - Create a `list_seo` page record. Writes live data.' The verb 'create' and resource 'list_seo page record' are precise. Distinguishes from siblings like updateWebPage, listWebPages, and deleteWebPage by mentioning them and their use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance. For example, when filename exists, recommends updateWebPage instead. Details workflows for profile_search_results pages, when to use createRedirect, and when to omit certain fields. Also explains when to use different seo_types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors beyond annotations: automatic cache refresh, no uniqueness enforcement, backslash stripping in widget_data, route-by-type rules, and post-creation verification. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bold headings and bullet points, but is quite lengthy. However, every section serves a purpose, and key info is front-loaded. A slight reduction could improve conciseness, but it's well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters and no output schema, the description provides a complete picture: creation process, uniqueness handling, field routing, return format, cache behavior, and verification steps. References listWidgets for full field list. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 50% schema coverage, the description compensates extensively: explains widget_name format with regex, pre-check uniqueness logic, auto-suffix flow, routing by type (HTML/CSS/JS), common fields, and post-create verification. Adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a widget - Create a new widget (reusable HTML/CSS/JS component). Writes live data.' It identifies the resource (widget) and the action (create), distinguishing it from sibling tools like updateWidget, listWidgets, and getWidget by mentioning them under 'See also'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use: 'Use when: programmatically adding a new reusable block to embed via [widget=Name] shortcode on pages or email templates.' It notes rarity and alternatives (BD admin UI), and references sibling tools for checking uniqueness and verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond destructiveHint annotation by explaining permanence, unrecoverability, orphan metadata, and return format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with sections. Every sentence adds value: purpose, usage, requirement, caution, alternative, return message.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a simple destructive tool; covers deletion impact, confirmation guidance, and return format despite no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description states required field_id and its role in context. Parameter name is self-explanatory; could explicitly state it's the ID of the form field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool deletes a form field permanently. The description distinguishes it from sibling tools like updateFormField by emphasizing destructive nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' condition, warns of orphan metadata, includes 'See also' for alternative, and advises user confirmation for bulk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description adds: permanent deletion, cannot be undone, child items become orphaned, no soft-delete available. Discloses return format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured. Uses bullet points and clear sections. Each sentence adds value without redundancy. Approximately 5 sentences covering all necessary aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple delete tool. Covers purpose, usage, side effects (orphaned children), prerequisites (delete children first), return value, and alternative. With no output schema, the description adequately specifies the response format.
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?
Description states 'Required: menu_id.' While the schema already defines it as required integer, the description clarifies its necessity. Could briefly explain what menu_id is, but context of tool name makes it clear. Schema coverage is 0%, so description compensates partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a menu - Permanently delete a menu record by ID.' Uses specific verb and resource. Distinguishes from sibling tools by mentioning 'updateMenu' as alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: removing a menu container.' Provides exclusions: child items become orphaned, delete them first. Also warns about destructive nature and suggests confirming with user. Refers to alternative tool 'updateMenu'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true; description adds 'cannot be undone via API', 'no soft-delete', and a user confirmation warning. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for purpose, usage, required param, see-also, destructive warning, and return format. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (single param, no output schema), the description fully covers behavior, side effects, prerequisites, and expectations. The return value is explicitly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, but the single required integer parameter `data_id` is self-explanatory in context. Description mentions 'Required: data_id' and 'by ID', sufficient for a simple delete operation.
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?
Clear verb-resource pair 'Delete a post type' with explicit permanence. Distinguishes from sibling `updatePostType` by stating 'modify without removing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('removing a post type entirely'), warns of consequences (orphaned posts), suggests migration steps, and names an alternative tool (`updatePostType`).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: 'Permanently delete... cannot be undone via API', 'No soft-delete via API', and includes return format. It complements the destructiveHint and idempotentHint annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the most critical information (destructive nature, permanent deletion). Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-ID tool with no output schema, the description covers all necessary aspects: purpose, usage context, alternatives, behavioral implications, and return value. Annotations handle safety flags, and sibling differentiation is addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by stating 'Required: photo_id' and implying it is the ID of the photo. While minimal, it adds meaning beyond the bare schema. Baseline for zero params is 4, and this tool has one param, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a user photo - Permanently delete a userphoto record by ID.' It uses a specific verb and resource and explicitly differentiates from related tools like updateUserPhoto and updateUser with image actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use when: removing a photo attachment.' It also gives clear alternatives for member image management and advises confirming intent with the user before bulk use due to destructive nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, etc.), description reveals that email_body is stripped by default and how to retrieve it, describes the return format as an array within a success object, and mentions HTTP 404 for not found. This adds significant behavioral detail not present in annotations alone.
Agents need to know what a tool does to the world before 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, using bold headers and bullet points to organize critical information. Every sentence serves a purpose, and the most important details (read-only, required param, lean default) are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully explains the return structure and edge cases (empty/404). Combined with annotations and sibling references, it provides complete context for a simple get-by-id tool. No gaps remain.
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?
Description adds meaning beyond schema: it explains that include_body=1 is needed for editing and that email_body is the heaviest field. Though schema already covers include_body, the description reinforces its purpose and adds context about default behavior. email_id is simply noted as required, not adding much beyond schema, but overall useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single email template - Fetch a single emailtemplate record. Read-only.' It explicitly contrasts with 'listEmailTemplates (enumerate many)', distinguishing the tool from siblings. The verb 'get' and resource 'email template' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes 'Use when: fetching one template's HTML body and subject for edit.' and 'Required: email_id.' It also advises when to set include_body=1 and references the alternative listEmailTemplates for enumeration, providing clear usage context and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Read-only' and details the return shape, listing specific fields and explaining the effect of the include_raw parameter. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds valuable context without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a clear structure with sections for main purpose, usage condition, required parameter, return details, and cross-reference. Every sentence adds value with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers all necessary aspects: purpose, when to use, required parameter, return structure, and parameter behavior. Annotations and schema provide complementary info, making the overall context complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by identifying inquiry_id as a path parameter and explaining that include_raw=1 returns raw HTML. Schema coverage is 50% (only include_raw has a description), so the description compensates partially, but could have elaborated on the purpose of each field in return.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Forms Inbox submission', and specifies it retrieves a single item by inquiry_id. It also distinguishes itself from sibling tools by being a read-only retrieval, contrasting with list or mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: you hold an inquiry_id from listFormInquiries' and provides a 'See also' reference to the enumeration tool. This guides the agent precisely on when to use this tool and how to obtain the required ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds significant context beyond annotations: it is a wrapper-native synthetic tool, Range-GETs first 64KB, parses JPG/PNG headers, does not proxy to BD. Also explains batch mode behavior (parallel probing, per-URL error handling) and unsupported format fallback. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (main purpose, batch mode, caller contract). Information is front-loaded. While some details could be tightened, the length is justified given the complexity of batch mode and error handling. Slight redundancy in 'Rule: Image dimensions' reference could be shortened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description thoroughly explains return values (width, height, format, aspect_ratio, orientation) and batch response envelope. Covers error scenarios (404, timeout, parse fail, unsupported format) and how to handle them. Complete for a probing tool with no nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters described in schema). Description adds substantial meaning: for `url` specifies it must respond to Range request for first 64KB and be a canonical image URL; for `urls` explains batch mode details (comma-separated, up to 50, parallel probes, response envelope format in input order, failure isolation). This exceeds the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Probe an image URL and return its dimensions + orientation'. Specific verb and resource. Distinguishes from sibling tools by specifying its niche use in content-creation skills, which no other sibling appears to cover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidelines: when to use (verify image orientation before committing to feature-image fields), batch mode preference for 2+ candidates, caller contract to filter to .jpg/.jpeg/.png, and error handling instructions. Also references related rules ('see also'). Provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the lean-by-default keep-list structure, how to restore extras via include_extras=1, the return format (status, message array containing record), and the read-only nature. Annotations already mark readOnlyHint=true, idempotentHint=true, and the description aligns perfectly with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, lean-by-default, use when, required, see also, returns). It is concise yet informative, with each sentence providing distinct value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the return format and the lean-by-default behavior. It also addresses when to use this tool versus listMenus. For a read-only single-record retrieval tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the input schema by explaining that menu_id is required and that include_extras restores 'styling/target/rel/json_meta'. Since the schema only describes include_extras in detail, the description compensates for the missing menu_id description and clarifies the extras behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get', 'fetch') and resource (single menu record). It explicitly distinguishes itself from the sibling tool 'listMenus' by saying 'Child items are fetched separately' and 'See also: listMenus (enumerate many).'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance with 'Use when: fetching one menu's metadata' and contrasts with when to use a sibling tool. It also states the required parameter and the lean-by-default vs extras behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc. Description adds extensive behavioral context: lean-by-default keep-list, code-field master-fallback behavior, reserved data_types returning empty message, and related rules. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is long but well-structured with bolded section headings. Front-loaded with purpose. Some repetition of code field names, but overall efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (5 params, special behaviors, no output schema), description covers all necessary details: usage context, parameters, special cases, related tools, and return format. Highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, but description adds significant meaning to each parameter: explains include_code's master-fallback and grouped edit requirement, lists fields for include_review_notifications, describes include_extras bundle. Goes well beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single post type - Fetch a single posttype record. Read-only.' It specifies the verb and resource, and distinguishes from siblings like listPostTypes and updatePostType.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: checking the configuration of one post type... Commonly followed by getPostTypeCustomFields... Also the canonical read before any updatePostType code-field edit.' Also notes reserved data_types and alternatives, providing excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: it details the response shape, field semantics, and caching recommendation. It also mentions auth method and rate limit. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, caching advice, response shape, field semantics, and rationale. It is front-loaded with the main purpose. Despite length, every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the response shape and field semantics, covering every relevant field. It also includes caching strategy, auth details, and rate limit. The tool's role is uniquely defined among many siblings.
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?
There are zero parameters, so schema coverage is 100%. The baseline for 0 params is 4. The description does not need to add parameter semantics but instead thoroughly explains the output fields, which adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get site-level identity, locale, currency, and brand-image URLs.' The verb 'Get' and the resource 'siteInfo' are explicit. The tool is distinct from siblings like getUser or listCities, and the description emphasizes its role in providing foundational site context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises agents to call this once per session and cache the results, noting that values rarely change mid-conversation. It also explains why calling early is beneficial for shaping subsequent decisions, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Matches annotations (readOnlyHint, idempotentHint) and adds details: default lean output, opt-in for full schema, return format, and even broader classification context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized and front-loaded with essential info, but somewhat long due to extra classification details. Still efficient for the depth provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a get tool: describes behavior, parameters, output format, and relationship to other tools. No output schema, but return structure is explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: profession_id required as path parameter, include_category_schema explained with effect on output. Schema has 50% coverage but description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches a single TOP-level category by profession_id, read-only. Distinguishes from sibling tools like listTopCategories and listSubCategories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (have profession_id, need full record), when-not-to (use listTopCategories for enumeration), and lists alternatives with specific use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds return format '{ status: "success", message: [{...record}] }' and mentions empty/404 on not found, which are helpful behavioral details. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise: a single sentence plus structured sections (Use when, Required, See also, Returns). Every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter, the description covers purpose, usage, parameter, return format, and error cases. It is complete and leaves no ambiguity.
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?
Only one parameter 'id' with no schema description (0% coverage). Description states 'Required: `id`' and 'by ID', adding context that id is the identifier for the unsubscribe record. It could be improved by clarifying what the id refers to, but it's sufficient for a single param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single unsubscribe record' and specifies read-only. It uses a specific verb and resource, and distinguishes from sibling 'listUnsubscribes' by noting this fetches one record 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: checking one unsubscribe record by ID.' and provides 'See also: listUnsubscribes (enumerate many).' This gives clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, etc.), the description discloses critical behavioral traits: the need for agent-side verification of (database, database_id) pairs to prevent silent data corruption. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded with purpose. Slightly verbose due to safety warnings, but every sentence is justified; could tighten slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fully complete given no output schema: covers purpose, parameters, usage guidelines, safety warnings, and return format. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the input schema: explains the optional params as intent documentation and the agent-side verification procedure, complementing the 67% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single metadata record by meta_id, differentiating it from listUserMeta for enumeration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: fetching one metadata row by meta_id' and provides detailed safety verification steps to avoid data corruption. Also references sibling tool listUserMeta.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and idempotent, and the description reinforces 'Read-only' and adds behavioral details: returns 400 with misleading error when no billing record, return format including MariaDB zero-date sentinel, and notes that subscription_details may be false. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded summary, and all information relevant. Slightly verbose (e.g., long error handling explanation) but every sentence adds value; could be tightened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully details return structure, edge cases (unpaid invoices, zero-date, subscription_details false), and error handling. Covers all needed context for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds mutual exclusivity rule, explains the difference between user_id (standard BD ID) and client_id (WHMCS record), and provides guidance on default behavior. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get member billing transactions (invoices)' and distinguishes from sibling getUserSubscriptions by specifying invoices vs. subscriptions. The verb 'get' and resource 'transactions/invoices' are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (e.g., see invoices, billing history) and provides parameter selection guidance (prefer user_id, use client_id only when you have it). Also warns about a misleading error and how to interpret it. 'See also' references relevant siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc. Description adds value by detailing the lean-by-default behavior, explain which include flags restore which fields, and states return format. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with sections (use when, required, lean-by-default, flags, see also, returns). It's slightly lengthy but every sentence adds value. Front-loaded with purpose. Could be more concise but not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (4 params, no nested objects, no output schema), the description is complete. It covers purpose, usage, parameters, return format, and relationships with siblings. No gaps for expected agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description greatly enhances understanding by explaining the lean default and the purpose of each include flag, including how to use them before updateWebPage edits. Goes well beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single page' and 'Fetch a single web page by seo_id. Read-only.' It distinguishes from siblings listWebPages (enumerate) and updateWebPage (modify) by specifying the use case of fetching metadata before editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: fetching one page's metadata... before editing.' Provides guidance on resolving seo_id via listWebPages, and references sibling tools as alternatives. Includes a clear rule for when seo_id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavioral traits beyond annotations: pagination details (cursor-based), return format including a known typo ('locaiton_id'), error handling through empty results pattern, auth requirements, rate limit (100 req/60s), and system-critical nature with warnings against create/delete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is long but well-structured with clear sections (purpose, usage, pagination, filter/sort, return format, system-critical note). Every sentence adds value, though it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description fully documents return structure, fields, and edge cases. Also covers auth, rate limits, and system-critical constraints, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds substantial meaning: explains pagination parameters (page, limit), filter/sort fields (property, property_value, property_operator, order_column, order_type) with specific examples and references to external rules, and clarifies that filter column keys must match response rows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List cities (location-based search & SEO slugs)' and explains its use for resolving city names to slugs and discovering seeded cities. It distinguishes itself from siblings like listStates by focusing on cities for SEO slug generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use (resolving city name to slug, discovering cities) and when not to (creating cities should be left to member signups, deleting is omitted). References alternative actions like updateCity for corrections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, etc. Description adds lean-by-default keep-list, flag behavior, pagination details, return format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Slightly long but well-structured with sections. Front-loaded with purpose. Could be trimmed slightly, but each section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, usage, parameters with flags, pagination, filters, return format. References external rules for deeper detail. No output schema, but return shape is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds context: purpose of include_* flags, lists specific fields restored, explains filter/sort parameters referencing external rules.
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?
Clear verb 'list', resource 'membership plans', and scope 'paginated enumeration'. Distinguishes from sibling getMembershipPlan. Read-only is stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: discovering subscription_id for createUser, essential prerequisite. Also mentions pagination and filtering guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and destructiveHint false. The description adds significant context: 'Lean-by-default keep-list,' behavior of include_extras, default-merge models, silent-drop detection, and pagination semantics. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose, keep-list, use-when, pagination, filter/sort, see-also, returns. Each sentence adds value, and the most critical information is front-loaded. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description provides complete return structure, explains merge behavior, and references rules for pagination and filters. It covers all aspects needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the keep-list, how include_extras works, and filter operator behavior (e.g., silent drop, compound filters). This provides meaningful guidance beyond parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List menus - Paginated enumeration of menu records. Read-only.' It specifies the verb (List), resource (menus), and includes pagination. It distinguishes from siblings like 'listMenuItems' and 'getMenu' by contrasting use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: enumerating navigation menus on the site' and 'For items within a menu use listMenuItems with menu_id filter.' It provides clear context on when and when not to use this tool, with an alternative tool named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: lean-by-default keep-list behavior, pagination semantics, filter/sort details, silent-drop detection, and the effect of include_* flags. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for use, pagination, filter/sort, and see also. It is front-loaded with purpose and read-only status. Though lengthy, every sentence adds value; minor redundancy (e.g., 'Same keep-list as listSingleImagePosts') is acceptable for cross-reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters and no output schema, the description thoroughly explains the return shape (status, pagination fields, lean records), pagination behavior, filter operators reference, and hints to rules. It provides nearly everything an agent needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds extra meaning: it explains the lean keep-list, that include_content returns HTML, include_author_full returns sensitive fields, and how filters interact with the keep-list. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List album groups - Paginated enumeration of portfoliogroup records. Read-only.' It distinguishes from sibling listSingleImagePosts by specifying use for multi-image post types. The purpose is specific and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage context: 'Use when: enumerating photo-album / gallery-style posts... For single-image post types use listSingleImagePosts.' It also references getMultiImagePost for single record retrieval, offering clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description aligns with annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and adds details: lean-by-default keep-list, include flags behavior, type_of_feature enum, reserved data_types special behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is lengthy but well-structured with bold section headers, bullet points, and clear front-loading of purpose. Slightly verbose due to extensive details, but every sentence adds value and is organized logically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema but description thoroughly covers return format, pagination, filtering, lean-by-default, include flags, special data_types, and references to related rules. Complete for a complex list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100%, but description adds significant context beyond schema: explains lean-by-default keep-list, when to use include_code (editing templates), type_of_feature enum meaning, reserved data_types filtering. Each parameter's purpose is enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List post types - Paginated enumeration of posttype records. Read-only.' It uses a specific verb 'list' and resource 'posttypes', and distinguishes from siblings like 'getPostType' (single record) and create/update/delete tools by name and read-only hint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use when: discovering which post types exist on this site AND their data_type families... Use this BEFORE calling either create endpoint to pick the correct tool.' Also mentions reserved data_types and alternatives like 'listUsers', providing clear when-to and when-not-to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds substantial behavioral detail beyond annotations: lean-by-default keep-list semantics, silent-drop behavior for wrong property names, fields_only typo error behavior, pagination caveats, and filter operator limits. This is rich, non-redundant 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?
Despite being long, every section earns its place: use-when guidance, keep-list enumeration, flag explanations, pagination/filter rules, return shape, and sibling alternatives. Bolded labels and bullet-like structure make it scannable. It is detailed but not redundant; front-loads the core purpose and then layers operational specifics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 params and no output schema, the description fully compensates: it explains the return JSON shape, pagination semantics, filter/sort rules, field-selection flags, and error behavior. It also covers edge cases like silent empty results and unknown field name errors. This is comprehensive enough for an agent to use the tool correctly without external docs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed per-parameter descriptions, so baseline is 3. The description adds a cohesive explanation of the lean-default design and how include_* flags restore fields, which is beyond the individual schema descriptions. It also groups the filter/sort parameters into a meaningful operational pattern, adding value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List posts - Paginated enumeration of post records. Read-only.' and clearly specifies that it enumerates single-image post families. It explicitly distinguishes itself from listMultiImagePosts by noting data_type=4 requires the sibling tool. This is a specific verb+resource+scope with 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' context (blog articles, events, jobs, coupons, videos, discussions), states when NOT to use (data_type=4 means use listMultiImagePosts instead), and points to getSingleImagePost for single record retrieval. It also gives concrete filter usage examples, covering when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Read-only behavior aligns with annotations. Adds pagination details, filter guard, duplicate handling, and return format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bold rules, but somewhat lengthy. However, complexity justifies the length, and content is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: pagination, filters, identity, duplicates, common database values, and return format. No gaps given the tool's complexity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond the 100% schema coverage: explains compound identity, safety guards, wrapper translation, special value parameter, and filter style restrictions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List user metadata records - Paginated enumeration of users_meta records (EAV key/value table). Read-only.' Differentiates from siblings like getUserMeta and deleteUserMeta via explicit 'See also' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive when-to-use guidance: identity rules, pagination, filter styles, and explicit alternatives. Includes safety guard requirements and warns against mixing filter styles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (read-only, idempotent), description reveals lean-by-default behavior, pagination cursor-based, filter error handling (silent drops, BD misleading errors), and specifics like card_info field behavior. Adds substantial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While long, the description is well-structured with sections and bullet points, front-loading purpose and then providing necessary details. Every sentence adds value; no redundancy given complexity. Could be slightly more terse but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (19 parameters, extensive filtering), the description is complete: covers pagination, filtering, sorting, field selection, error handling, related tools, and even profile URL construction. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds significant value by detailing which include flags restore which fields, explaining filter operator usage, compound filter arrays, and profile URL construction, far exceeding schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists members/users with pagination, filtering, and sorting. It distinguishes itself from sibling tools like searchUsers and getUser by specifying their appropriate use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (reports, exports, bulk updates) and when not to (enumerating cities). Mentions alternatives searchUsers, getUser, and listCities. Also guides on resolving filter values via other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which indicate not read-only and not destructive), the description discloses: 'SIDE EFFECT: sends real emails to real members', 'Not a dry-run - emails go out immediately', and returns a standard response envelope. This adds critical 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings and bullet points, front-loading the main action. It is slightly lengthy but each sentence adds value, especially the warnings. Minor redundancy could be trimmed but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, the description covers the matching logic, side effects, return format, and prerequisite lead relationship. No output schema exists, but the return envelope is described. Complete given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, lead_id, is described as required and must reference an existing lead created via createLead. This adds meaning beyond the schema, which only specifies type integer. The description provides necessary constraints for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Auto-match lead to members' and explains it triggers automatic matching and sends notification emails. It distinguishes from sibling tools like createLead and createLeadMatch by specifying the automatic matching and emailing behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: after creating a lead or needing to redistribute an existing one. Also warns to confirm with user before calling on production data, and notes it's not a dry-run. This provides clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral details: it returns a distinct output structure, explains what the output includes (rendered HTML with auto-wrapped style/script), and notes that CSS/JS are omitted if empty. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings, bullet points, and clear sections. Despite length, every sentence adds value—no redundancy. Information is front-loaded with purpose and warning, and structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains the return format (distinct envelope with status, message, name, output) and details output contents. It also references related tools for further context. The tool is a simple read-only operation, and the description covers all necessary aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 2 parameters, with 50% description coverage (widget_id lacks description). The description adds that the tool requires either widget_id or widget_name, and notes that widget_name lookup is case-sensitive and must match exactly. This adds necessary clarity beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a widget to HTML and explicitly marks it as a diagnostic tool only, distinguishing it from production usage. It also mentions it returns BD's rendered HTML output, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (when user reports a broken widget, for troubleshooting render pipeline) and when not to use (never for production delivery). It references a specific rule and lists related tools (getWidget, updateWidget) for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds extensive behavioral context beyond annotations: PATCH semantics with all-or-nothing saves, automatic cache refresh, master-fallback on GET, trust level for code fields, and destructive potential of certain changes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-organized with sections and front-loaded critical info (cache refresh, required data_id, disambiguation). The repetitive opening 'Update a post type - Update a post type' is slightly inefficient, but overall structured given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary context: field groups, safe/unsafe mutations, special Member Listings rules, code edit workflow, _clear_fields mechanism, and return format. No output schema, but the return structure is documented. Exceptionally complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description still adds rich semantics: code field group rules, Member Listings cheat-sheet and guardrails, trust levels, and workflow explanations. This goes far beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a post type' and provides specific actions like toggling active/inactive, renaming, changing display counts, etc. It distinguishes from siblings by mentioning related tools (getPostType, listPostTypes, deletePostType) and provides disambiguation rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool (e.g., toggling, renaming, editing search-results UI) and when not to (e.g., never mutate listed system fields). It provides alternatives (see also) and detailed guardrails for Member Listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable behavioral details: 'Fields omitted are untouched', 'Writes live data', the note that post_title rename does not update the slug, the behavior of _clear_fields, and timezone rules for dates. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear sections (summary, use when, required, enums, behaviors, see also, returns). It is front-loaded with essential purpose. While verbose, every sentence adds value; a very minor deduction for length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (29 parameters, no output schema), the description is exceptionally complete. It explains the return format, cross-references other rules and tools (e.g., 'Rule: URL slug rename', 'getSingleImagePost'), and covers edge cases like timezones and clearing fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 66% schema coverage, the description adds significant meaning for many parameters: post_image requirements (landscape orientation, URL format, auto_import), post_promo relationship (must send both), post_category discovery via other tools, _clear_fields special behavior, date formats and timezone rules, and more. This compensates for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'post', and specifies that it updates an existing post record by ID. It differentiates from siblings like createSingleImagePost and deleteSingleImagePost by stating 'Update an existing post record' and referencing them in 'See also'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool: 'editing post content, switching from draft to published, updating post title/caption, or correcting post metadata.' It also provides exclusion context: moving to a different post type is rare and requires validation via data_id. Additionally, it references sibling tools for creation and deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description extensively discloses behavioral traits beyond annotations, such as PATCH semantics, filename regeneration, email uniqueness controlled by site settings, field validation quirks, parameter interactions (e.g., member_tag_action, credit_action), and processing delays. This adds significant value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with sections, bullet points, and bold headings. It front-loads the core purpose and then provides detailed specifics. While it could be slightly more concise, the length is justified by the tool's complexity (60 parameters, many edge cases).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count, lack of output schema, and complex interactions, the description is remarkably complete. It covers return format, parameter interactions, validation quirks, disambiguation rules, and references external rules. No major gaps are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 83% schema description coverage, the description adds substantial meaning by explaining parameter interactions, edge cases (e.g., profession_name silent failure), formatting requirements (e.g., URL fields, token), and behavioral nuances (e.g., additive vs. replace semantics for tags and categories). This goes well beyond the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing member/user' with PATCH semantics, explicitly distinguishing from createUser (new) and deleteUser (permanent). It identifies the specific verb and resource, and differentiates from siblings by mentioning alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('Use when: changing any field on an existing member') and when not to ('Prefer active=3 (Canceled) over deleteUser - reversible'). It also includes a safe pattern for email uniqueness pre-check, offering clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral details: the return is a bare array (not wrapped), the silent-fallback behavior when form_name is invalid, the exact shape of fallback responses, and that post_category values do not come from this endpoint. It also highlights a whitespace trimming issue. This adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (Use when, Required, Returns, Silent-fallback warning, post_category note). It is front-loaded with the purpose, and every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description fully compensates by detailing the return format, edge cases, fallback detection, and cross-references to other tools. An agent has all information needed to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers the parameter with 100% description, the tool description adds examples ('blog_article_fields, events_fields') and clarifies the impact of an invalid form_name (fallback). This goes beyond the schema's 'Form slug for the post type'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves custom fields for a specific post type form, with a specific verb 'Get' and resource 'post field definitions'. It distinguishes from siblings by specifying the use case of discovering per-post-type custom fields before building create/update payloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('discovering the per-post-type custom fields before building a create/update payload'), what is required ('form_name'), and provides a warning about silent-fallback with instructions to verify form_name via listPostTypes. Also gives guidance on handling post_category.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses a misleading error scenario (HTTP 400 + 'user_id or client_id is required' when member has no billing record) and how to interpret it. Describes return format in detail. No contradiction with annotations (which already indicate read-only, idempotent, non-destructive).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (Required, Empty result, Use when, See also, Returns). Every sentence adds value, and the length is justified given the complexity (error handling, parameter choice). No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, parameter constraints, error handling, use cases, related tools, and return structure. Despite no output schema, the description fully explains the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: exactly one required, default to user_id, client_id for power-users bypassing lookup. Schema already has descriptions, but the usage guidance is invaluable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves member subscription/membership-plan history. It names the resource and distinguishes it from siblings like getUserTransactions (invoice-level) and getUser (profile-level references).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (checking membership plan, billing cycle, etc.) and provides a 'See also' section with alternatives. Includes specific guidance on choosing between user_id and client_id, defaulting to user_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses lean-by-default behavior (keep-list stripping code fields), explains include_code parameter to restore them, and notes the return format. Annotations already indicate read-only, idempotent, non-destructive; description adds valuable context on default response and when to use include_code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (lean-by-default, use when, required, see also, returns). Every sentence informative, no redundancy. Appropriate length for comprehensive tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 params, one optional enum, no output schema, the description covers purpose, usage, parameters with semantics, return format, and related tools. Complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: clarifies widget_id is required path parameter, explains include_code as opt-in for code fields and its necessity before updateWidget. Schema coverage is 50%, description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get a single widget' and 'Fetch a single widget record by widget_id', with specific verb and resource. It distinguishes from siblings like listWidgets (enumerate) and updateWidget (modify).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: you have a widget_id... and want the widget's SOURCE code to edit or audit.' Provides alternative for preview via shortcode. Lists see-also references for enumeration and modification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: 'Lean-by-default: email_body stripped', pagination semantics, filter/sort behavior, and the return format. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (use when, lean-by-default, pagination, filter/sort, see also, returns). Front-loaded with the main action. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, pagination, filtering, and no output schema, the description thoroughly explains the return format, cursor-based pagination, filter operators, and the lean-by-default behavior. It references rule documents for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds significant meaning beyond field names: explains why `include_body` defaults to 0 (heaviest field), multi-condition filtering with parallel arrays, operator taxonomy (word vs symbol forms), and references to rules for silent-drop detection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List email templates - Paginated enumeration of emailtemplate records. Read-only.' using a specific verb and resource, distinguishing it from siblings like `getEmailTemplate` (single record) and `createEmailTemplate`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'enumerating the site's transactional/marketing email templates before editing. Common audit: before bulk updating.' Also references a sibling tool and includes exclusions like 'See also: getEmailTemplate (single record by ID).'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description details pagination, filter/sort semantics, return structure, and default-merge behavior, adding significant 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?
Well-organized with headings and bold terms, front-loaded purpose, each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, it provides the return shape and default-merge note, making the tool fully understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description still adds meaning by explaining defaults, array usage, operator types, and silent-drop detection, beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists forms with paginated enumeration, specifies it is read-only, and distinguishes from sibling tools like getForm and listFormFields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use (enumerating forms), mentions child fields are fetched separately via listFormFields, and points to getForm for single record retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds key behaviors: truncation of review_description, pagination cursor semantics, filter/sort rules, and performance considerations for include_full_text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded purpose. Every sentence adds value without redundancy. Despite length, it remains scannable and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all key aspects: pagination, filtering/sorting, truncation, return format, usage guidance, and performance considerations. No missing context for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds rich semantics: explains lean default truncation, pagination cursor usage, compound filter arrays, operator enumerations, and performance note for include_full_text.
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?
Opens with 'List reviews - Paginated enumeration of review records. Read-only.' Clearly states verb (list), resource (reviews), and distinguishes from sibling getReview for single records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases: moderation queues, exporting, reports, pagination. Specifies when to use getReview instead, and mentions keyword-in-body filtering approach.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: describes it as a safe troubleshooting step, explains the side effects (clearing caches), return format, error behavior for invalid scope, and the fact it is undocumented publicly. No contradiction with annotations; readOnlyHint=false aligns with write 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?
Well-structured with clear sections: purpose, usage, parameter details, exceptions, and return value. Every sentence provides critical information, no redundancy. Front-loaded with verb+resource. Appropriate length for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: what it does, when to use, parameters with examples, return format, error cases, and relationship to sibling tools. No output schema, but description details the return object sufficiently. Edge cases (invalid scope) are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but description adds richer context: scope parameter targets a specific area for speed, full parameter adds heavier operations and when to use. Includes example responses with explanations of areas_refreshed list. Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool refreshes BD's internal caches for templates, themes, widgets, menus, and pages. The verb 'refresh' and resource 'site cache' are specific, and it distinguishes from sibling CRUD operations (create/update/delete) which do not have cache refresh as primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after admin edits not appearing), when not needed (auto-refresh after certain create/update tools), and what to avoid (routine noise). Also provides guidance on optional parameters (scope and full) with appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosed 'Writes live data,' 'Fields omitted are untouched,' and detailed the _clear_fields parameter behavior. Annotations confirm non-readonly and non-destructive nature, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear sections (Use when, Required, Enums, See also, Returns) and concise sentences. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, parameters, behavior (including clearing fields), return format, and references to related tools. Adequate for a mutation tool without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds value by repeating enums in plain language and explaining the _clear_fields parameter with examples, beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Update a data type' with specific verb and resource. It distinguishes from siblings by listing createDataType and deleteDataType as alternatives, making the purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes 'Use when: renaming a data type.' and 'Required: data_id.' along with 'See also:' references to create/delete alternatives, providing explicit usage context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses 'Writes live data', 'Fields omitted are untouched', and the exact return format. Annotations indicate idempotent and open world; description adds operational context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: uses bold headers, single sentences for each section, no fluff. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, it explicitly describes the return format. Covers required param, optional params behavior, and complex clearing rule. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: describes _clear_fields behavior in detail (e.g., must use to clear fields, works on EAV rows), and notes that omitted fields remain untouched. Schema coverage is 67% but description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a tag relationship' and specifies 'Update an existing tagrelationship record by ID', distinguishing it from createTagRelationship and deleteTagRelationship mentioned in 'See also'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when: adjusting a tag-relationship record's metadata', lists required param 'id', and provides alternative tools via 'See also'.
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:

[![brilliant-directories-mcp MCP server](https://glama.ai/mcp/servers/brilliantdirectories/brilliant-directories-mcp/badges/card.svg)](https://glama.ai/mcp/servers/brilliantdirectories/brilliant-directories-mcp)

Score Badge

Copy to your README.md:

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

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