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

The description goes well beyond the annotations by explaining non-atomic behavior, validation before writes, the temporary member lifecycle, concurrency hazards, comma restrictions, and detailed status reporting. The annotations already indicate this is a non-read-only, non-idempotent operation, and the description expands on those traits extensively 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but densely packed with behavior the agent must know to call the tool safely and correctly. It is front-loaded with the core purpose and 'Use when' guidance, then progresses to examples, validation rules, failure semantics, and return values, with each section earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and absence of an output schema, the description fully compensates by documenting the return structure, all status values, temp_member outcomes, retry guidance, and how to read sub-category ids afterward. It also cross-references the relevant sibling tools, making the definition complete for an 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already covers 100% of the parameters, the description adds substantial operational meaning: the Parent=>Child syntax, the 25-entry maximum, the reuse semantics for existing top categories, the no-comma rule, and concrete input shapes. This goes far beyond the schema's field-level documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: creating a full category taxonomy (top, sub, and sub-sub categories) in one call. It distinguishes itself from the sibling tools createTopCategory and createSubCategory by explaining that those are only for single categories with specific fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit 'Use when' guidance and explicitly names the alternatives (createTopCategory, createSubCategory) and the conditions under which to use them instead. It also covers operational usage constraints like avoiding concurrent calls and sending the whole taxonomy in one call.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations only say the tool is not read-only, not idempotent, not destructive, and open-world. The description adds substantial behavioral detail: writes are immediately live on the public site, BD does not enforce uniqueness, the wrapper auto-suffixes filename collisions, and a server-side pre-check is recommended. These are non-obvious behavioral traits an agent needs to invoke the tool safely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with bolded section headers and front-loaded purpose, use-when, and required fields. Some content, such as the member classification explanation, is broader context rather than strictly necessary to invoke the tool, which keeps it from a perfect conciseness score, but everything is organized and purposeful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters, no output schema, and a rich sibling ecosystem, the description covers nearly everything needed: required fields, pre-create uniqueness checks, collision behavior, parameter guidance, return shape with service_id, and integration with related tools. Nothing critical is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 63% schema description coverage, the description adds meaningful meaning beyond the schema: master_id semantics for sub-sub-category nesting, profession_id as the parent Top Category ID, filename as the URL slug with a default slug generation rule, and the notion that name must be a single name, not a comma-separated list. lead_price and sort_order remain thin, but they are optional and lower-risk.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Create a new SUB-level member category under an existing Top Category.' It also differentiates itself from createTopCategory and createCategoryTree, so an agent can immediately tell what this tool uniquely does and which sibling should be used instead.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Use when' section explicitly lists the conditions for choosing createSubCategory, and states that createCategoryTree should be used for every other category create. It also names alternatives like createTopCategory, updateSubCategory, listSubCategories, createUser, and updateUser, plus the pre-check workflow, making the decision boundary unambiguous.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations only indicate readOnlyHint=false and idempotentHint=false, but the description reveals key behaviors: writes are immediately visible on the public site, filename uniqueness is NOT enforced by BD, duplicate slugs make resolution undefined, and the wrapper auto-suffixes filename on collision (-1...-20). This is exactly the behavioral context an agent needs beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and sectioned, but it is far longer than necessary and contains direct repetition: the 'Use createTopCategory or createSubCategory only for...' sentence is nearly duplicated by the later 'Use when:' section. The multi-step 3-tier workflow, member classification model, and sub-sub-category digression are useful domain context but not essential for invoking this specific tool, making it bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description states the exact return shape, required parameters, pre-check procedure with server-side filter-find, collision handling, and integration points like profession_id on user records. It is complete enough for an agent to call the tool safely and correctly in a real workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning: filename defaults to lowercased hyphenated name with percent-encoding, desc is an internal label and NOT an SEO description, keywords are fuzzy-match synonyms not SEO meta keywords with format examples, and each optional field is clarified. This goes well beyond the schema's short property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with explicit 'Create a new TOP-level member category. Writes live data,' naming a specific verb and resource. It also clearly distinguishes createTopCategory from createSubCategory and createCategoryTree by defining the top-level tier of the 3-tier classification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use and when-not-to-use guidance: only for a single category needing create-time field control or a custom filename, otherwise use createCategoryTree. Also names the alternative of passing profession_name to createUser for auto-creation, and lists related list/get tools. This is model routing guidance, not just a vague hint.

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

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

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.

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.

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.

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.

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.

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.