@aiwerk/mcp-server-ghl
Server Quality Checklist
Latest release: v0.2.0
- Disambiguation2/5
With 569 tools spanning dozens of domains, there is significant overlap. For example, many ad manager tools across Facebook, Google, and LinkedIn have analogous operations (e.g., get_entity, upsert_campaign) that could be confused. Additionally, multiple tools are duplicated between deprecated and current versions (e.g., saas_api_get_saas_plan and saas_api_get_saas_plan_deprecated), and some conversation tools overlap (add_inbound_message, add_outbound_message, send_a_new_message).
Naming Consistency4/5Most tools follow a consistent domain_verb_noun pattern (e.g., calendars_create_calendar, contacts_update_contact). However, there are minor deviations like 'conversations_live_chat_agent_typing' which lacks a verb, and inconsistent verb choices across domains (e.g., 'fetch' vs 'get', 'create' vs 'add'). Overall, the pattern is predictable and readable.
Tool Count1/5569 tools is an extreme count for an MCP server. Even for a comprehensive API like GoHighLevel, this is far beyond typical scope. It suggests a monolithic wrapper rather than a focused toolset, which increases complexity and selection difficulty for agents.
Completeness3/5The server covers an extensive range of domains (calendars, contacts, invoices, payments, social media, etc.) with many CRUD operations. However, the presence of deprecated duplicate tools indicates lack of cleanup, and some areas may have gaps (e.g., missing update/delete for certain entities). The breadth is impressive but not perfectly polished.
Average 2.4/5 across 509 of 569 tools scored. Lowest: 1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds zero behavioral context beyond the annotations. It does not mention side effects, required permissions, or any nuance of the update operation. The annotations declare readOnlyHint=false and idempotentHint=true, but the description contributes nothing to clarify behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified, not concise. It is a bare two-word phrase with no structure, no front-loading of key constraints, and no elaboration. It fails to earn its space by providing any useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters, 5 required, nested objects, and no output schema, this description is grossly inadequate. An agent would not know what this tool does beyond the name, cannot correctly fill required fields, and has no guidance on return values or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at only 50%, the description carries part of the burden for explaining parameters, but it says nothing about any parameter. It does not clarify what 'items', 'businessDetails', 'currency', or other fields represent, leaving the agent without guidance on how to populate these complex nested objects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update template' is a tautology that simply restates the tool name (invoices_update_invoice_template). It fails to specify what kind of template, what fields can be updated, or how it differs from related tools like invoices_update_invoice_template_late_fees_configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention relative tools, expected contexts, or any exclusions. It gives no indication of when an agent should pick this over other invoice template tools.
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?
The description adds no behavioral information beyond the name. Annotations indicate a write operation (readOnlyHint=false) but the description does not disclose side effects, requirements, or potential pitfalls. It offers zero value beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely brief, this is under-specification rather than effective conciseness. It lacks the substance needed for a tool with 14 parameters and 11 required fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with complex requirements, the description is severely incomplete. It does not mention output behavior, required field dependencies, or any important constraints, despite having no output schema to rely on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 36%, and the description does nothing to compensate. It explains no parameters, leaving agents without guidance on how to fill required fields like rawHTML, urlSlug, or imageAltText, which are not described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Blog Post' merely restates the tool name, providing no additional information about the action, resource, or scope. It does not distinguish this from sibling tools like blogs_update_blog_post or blogs_get_blog_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage context is provided. There is no guidance on when to use this tool versus alternatives, no prerequisites, no mention of required external lookups (e.g., author ID, category ID) that are critical for correct invocation.
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?
The description adds no behavioral information beyond what the name already implies. Annotations declare readOnlyHint false (a write operation) and idempotentHint false, but the description does not disclose any additional behavioral traits such as side effects, error conditions, or whether the operation requires a specific location context. With zero annotation richness, the description carries the full burden and fails entirely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (three words), which is concise but not effective. It lacks any structure or elaboration that could guide the agent. This is under-specification, not deliberate conciseness; there is zero information content beyond the tool's name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters, a write operation, and no output schema, the description is wholly inadequate. It gives no indication of required fields, the nature of the created entity, or the expected response. An agent has no way to call this tool correctly or understand its purpose without extensive external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9% (only locationId has a description). The tool description provides no parameter semantics whatsoever—it does not explain what 'name', 'email', 'address', etc. are for, nor does it mention that 'name' is required. It completely fails to compensate for the sparse schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Business' is a pure tautology—it simply restates the tool name without adding any meaning. It does not explain what a 'business' record is, what fields it involves, or how it differs from sibling tools like businesses_update_business or businesses_get_business. An agent cannot distinguish this from other business-related operations based on this description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool, what prerequisites exist (e.g., a locationId), or when alternatives like businesses_update_business would be more appropriate. There is no mention of context, exclusions, or selection criteria, leaving the agent without any usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false, but the description doesn't clarify side effects, authentication requirements, or record creation semantics. It simply repeats the verb, offering nothing that helps the agent anticipate behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), but this is under-specification rather than efficient structure. For a tool with 9 parameters and significant complexity, a pithy description is not appropriate. It lacks any front-loaded essential information that would help an agent decide rapidly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, 4 required, no output schema), the description is grossly inadequate. It does not explain what an opportunity is, how to populate fields, what values are valid for status, or what the response might contain. An agent cannot correctly invoke this tool without opening the schema and even then, key semantics remain ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (3 of 9 parameters have descriptions), and the tool description provides no parameter information at all. With low schema coverage, the description must compensate, but it doesn't. Even the required parameters (pipelineId, name, status, contactId) are unexplained beyond their names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description "Create Opportunity" is a tautology of the tool name. It states the verb and resource but adds no specificity about what an opportunity is, what data it requires, or how it differs from sibling tools like opportunities_update_opportunity or opportunities_delete_opportunity. It provides zero unique information beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or exclusions. An agent has no way to know when it should call this instead of opportunities_upsert_opportunity or opportunities_create_opportunity (which might also create).
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?
The description adds nothing beyond the annotations already provided (readOnlyHint=true, openWorldHint=true). It does not disclose behavior such as pagination requirements (page, limit, searchAfter), the meaning of the additionalDetails flags, or any side effects. With annotations covering safety, the description still contributes no behavioral context, so it scores minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two words), but this is under-specification rather than effective conciseness. It lacks any structure or detail needed to be useful. While it is concise, it fails to convey necessary information, so it rates low.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, a nested object, required fields, and no output schema. The description provides zero context about how to construct a valid call, what the response contains, or any constraints. It is completely inadequate for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only locationId has a description). The description 'Search Opportunities' provides no explanation of query syntax, how limit/page/searchAfter drive pagination, or the purpose of the additionalDetails object. It fails to compensate for the poor schema coverage of the other five parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Opportunities' merely restates the tool name and gives no information beyond the verb and resource already present in the name. It fails to specify what 'advanced' means or how it differs from the sibling 'opportunities_search_opportunity'. It is essentially a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention the simpler sibling 'opportunities_search_opportunity' or any other search tool, nor does it explain the context for using the advanced search (e.g., pagination or additional details flags). An agent is left without any decision support.
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?
The description adds no behavioral context beyond what annotations already indicate. It fails to disclose what the update does, side effects, permission requirements, or effects on existing configuration. Worse, it misleads by referencing late fees, which is not supported by the schema. This is a serious failure in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence, but it is factually wrong regarding the tool's purpose. It does not earn its place because it misinforms rather than informs, making its brevity counterproductive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is grossly incomplete. It fails to describe what the tool does, when to use it, or how to interpret the payment methods configuration. Given the nested object structure and the potential for confusion with sibling tools, the description is dangerously inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all parameters including paymentMethods and stripe. The description adds nothing and actively misleads by suggesting late fees, which is unrelated to the actual parameters. While the schema is clear, the description's contradiction undermines any value it might have had.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Update template late fees configuration' but the tool name and input schema indicate this is about updating payment methods configuration (paymentMethods with stripe). The description directly contradicts the tool's stated purpose, making it misleading rather than clarifying. An agent would be unable to discern what the tool actually does from this description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. Sibling tools like 'invoices_update_invoice_late_fees_configuration' and 'invoices_update_invoice_template_late_fees_configuration' exist, but the description provides no differentiation or conditions for selection. The misleading statement about late fees only adds confusion.
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?
Annotations indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds no behavioral context. It does not explain what duplication entails (e.g., creates a new campaign with same settings), what happens to existing entities, or any side effects. The description provides zero value beyond the annotations, which are already minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase, which is extremely under-specified. While it is front-loaded and has no wasted words, it lacks even the minimum necessary detail to be helpful. This is under-specification rather than conciseness, as it omits critical information about the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating operation with no output schema, the description is severely inadequate. It does not explain what the result of duplication is, whether it copies ads, ad sets, or just the campaign settings, or any integration requirements. An agent cannot reliably call this tool based on the description alone, making it incomplete in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (locationId has a description, campaignId does not). The description 'Duplicate campaign' adds no parameter information at all. It does not clarify what campaignId refers to or any constraints. Given the moderate schema coverage, the description should compensate, but it does not, leaving required parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Duplicate campaign' merely restates the tool name 'ad_manager_fb_duplicate_campaign' without adding any specificity. It does not distinguish from sibling tools like duplicate_ad or duplicate_adset beyond the resource name, which is already in the tool name. This borders on tautology and provides no additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives. The description does not mention any conditions, prerequisites, or when not to use it. With multiple sibling duplication tools (duplicate_ad, duplicate_adset), the lack of routing information leaves the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no behavioral traits beyond what annotations already imply. Annotations (readOnlyHint=false, destructiveHint=false) are minimal, and the description adds nothing about what resuming entails—side effects, state changes, or expected outcomes. It completely fails to enrich understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is under-specification, not conciseness. It is too terse to be useful and skips essential information. While front-loading is not an issue, the content is practically absent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that mutates state (resuming a campaign) with no output schema, the description is severely incomplete. It lacks any explanation of side effects, return values, or interaction with the broader ad manager system. It is inadequate for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description provides no explanation of campaignId or locationId. While the schema has a description for locationId (50% coverage), the tool description does not compensate for the undocumented campaignId or clarify parameter relationships. Schema coverage is moderate but the description adds zero value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Resume campaign' is essentially a tautology—it repeats the action implied by the tool name without adding any specific resource context or differentiating it from siblings like ad_manager_fb_pause_campaign or ad_manager_fb_publish_campaign. It states a verb and object but offers no distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., needing an active integration or paused campaign), and no exclusions. The description provides absolutely no context for selection.
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?
Beyond annotations (which already declare read-only, idempotent, non-destructive), the description adds no behavioral insight. It does not state whether it returns a single entity or a list, how IDs interact, or any other operational details. The description carries the burden for these traits but provides nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
While concise, it is drastically under-specified. A two-word phrase is not a useful description for a tool with nine parameters and multiple enums; it fails to convey any structure or essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters and no output schema, the description is completely inadequate. An agent cannot infer purpose, usage, or expected behavior from this terse text, making the tool nearly unusable without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The tool description adds no additional meaning, but the baseline of 3 is appropriate since the schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Get entities' is essentially a tautology of the tool name, providing no specificity about what entities (campaigns, ad groups, ads) or from which platform. It fails to distinguish from many sibling get tools like ad_manager_google_get_campaign_by_id or ad_manager_fb_get_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers zero guidance on when to use this tool instead of its many alternatives. No mention of use cases, required parameters, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what annotations already provide. Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description does not disclose pagination, return format, or any operational details. It fails to add any value beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. A concise description would still provide essential context in a few sentences. Here, it is a bare label that does not earn its place as a useful tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description is drastically insufficient. It does not explain what the tool does beyond the name, does not clarify the returned data, and offers no context on defaults or behavior. An agent would be unable to use this tool correctly based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation for any of the 9 parameters. While some parameters have descriptions in the schema (limit, query, status, campaignId, locationId, affiliateId), others like skip, toDate, and fromDate are undocumented in both the schema and the description. With schema coverage at 67% (not high), the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Commissions' states a verb and resource but is essentially a restatement of the tool name. It provides no scope, filtering, or differentiation from sibling list tools like affiliate_manager_list_affiliates or affiliate_manager_list_payouts. It is vague and does not specify what kind of commissions or any context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no exclusions. The description offers zero context for selection among the many list tools in the sibling set.
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?
The description adds no behavioral information beyond what the annotations already provide. Annotations indicate it's a non-read-only, open-world, non-idempotent, non-destructive creation operation, but the description does not elaborate on side effects, permission requirements, or any post-creation implications. With no added context, the description fails to enhance transparency 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, technically concise, but it is under-specified to the point of being content-free. It offers no explanation of what a calendar group is, what fields are needed, or any operational details. This is not genuine conciseness but sparse inadequacy, warranting a low score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 5 parameters and no output schema, the description is drastically incomplete. It does not explain the concept of a calendar group, the significance of required fields (name, slug, description), or expected outcomes. An agent has no way to correctly invoke this tool based on the description alone, making it contextually insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters with only 20% description coverage (only locationId has a description). The tool description does not mention any parameter, their purpose, or how they relate to creating a calendar group. Since schema coverage is low and the description provides zero compensation, parameter semantics are entirely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Calendar Group' restates the tool name verbatim (calendars_create_calendar_group) without adding any detail. It names the verb and resource but provides no differentiation from siblings like calendars_create_calendar, which could plausibly be confused for an identical purpose. This is essentially a tautology, offering no new information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever on when to use this tool versus alternatives. The description does not mention when to create a calendar group as opposed to a calendar, schedule, or other related creation operations. No context, prerequisites, or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, indicating a write operation; the description adds no additional behavioral context. It does not disclose what a 'notification' is, what happens on creation, any prerequisites, side effects, or response behavior. With no extra information beyond the name and annotations, this dimension is essentially empty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It lacks all necessary detail and structure. While there is no wasted text, the brevity is detrimental; it provides only a minimal phrase that does not earn its place as a useful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with two required parameters and no output schema, the description is grossly incomplete. It does not explain what a 'notification' is, how to construct the body, what the calendarId refers to, or what the expected result is. The tool cannot be correctly invoked based on this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (only 'body' has a description; 'calendarId' has none). The description provides zero additional explanation of the parameters. It does not clarify what the body array should contain or how calendarId is used. The tool description adds no semantic value beyond the schema, and it fails to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create notification' is a verb plus a vague resource, but it fails to specify that this is about calendar event notifications. It does not distinguish from other notification-related tools or the many calendars_* siblings. The verb is clear but the object is too generic to convey the tool's actual function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There are many sibling tools for calendars and notifications (e.g., calendars_create_event, calendars_create_calendar, calendars_get_event_notification), but the description gives no context on the intended use case or any conditions that would select this over others. Completely absent.
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?
The annotations (readOnlyHint, idempotentHint, destructiveHint false) already disclose the safety profile, but the description adds nothing beyond the literal 'Get notification'. It does not explain what constitutes a notification, whether it returns a single entity or list, or any side effects. Since the description carries the burden of behavioral context beyond annotations and fails to add any, this is a minimal score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this reflects under-specification rather than efficient conciseness. It front-loads only the bare verb and noun without any supporting detail. The lack of structure or elaboration makes it impossible for an agent to act correctly, so it scores low on this dimension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two required parameters, no output schema, and no parameter descriptions, the description is completely inadequate. It provides no information about the return value, expected behavior, or how parameters interrelate. This tool is unusable by an AI agent without external knowledge, so contextual completeness is essentially absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It does not mention calendarId or notificationId at all, leaving their meaning, format, or relationship entirely unexplained. With no enums or additional schema details, an agent has no way to correctly populate these required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get notification' states a verb and a resource, but it is ambiguous and fails to differentiate from the sibling tool 'calendars_get_event_notification'. The name suggests 'find' while the description says 'get', and no context is given about what a notification is in this domain. This is barely more specific than a tautology and provides no meaningful purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. With siblings like calendars_get_event_notification, calendars_create_event_notification, and calendars_update_event_notification, the description offers no context about the appropriate scenario, prerequisites, or differences from other tools. An agent has no basis to choose this tool over similar ones.
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?
Annotations indicate readOnlyHint=false, so it's a write operation, but the description adds absolutely no behavioral detail. It doesn't mention what gets created, whether duplicates are possible, or any side effects. Since annotations already carry the basic write signal, the description still fails to add any contextual depth beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, this is severe under-specification rather than effective conciseness. The description conveys no actionable information and fails to use the available space to provide any useful details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 23 parameters, complex nested objects, and no output schema, a two-word description is grossly insufficient. The agent receives no guidance on required inputs, expected behavior, or return values, making the tool nearly impossible to use correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13% (3 of 23 params have descriptions), and the description doesn't compensate at all. It provides no explanation of the parameters, their purpose, or how they interact, leaving the agent to parse a large schema with many optional and nested fields without any semantic aid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Contact' is essentially a tautology of the tool name, providing no differentiation from sibling tools like contacts_upsert_contact. It fails to specify what kind of contact, what system, or what creation involves, leaving the agent to infer everything from the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as contacts_upsert_contact, or on prerequisites like authentication or required context. The description offers no usage context, so the agent has no basis for selecting this tool appropriately.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds zero behavioral context—it does not mention that this returns a single task, whether it requires existing records, or any special behavior. It contributes nothing 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.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words with zero informational content. This is not concise specification; it is under-specification. It fails to provide any structure or front-loaded details that would help an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and sibling tools that include get_all_tasks, delete_task, and update_task, the description is incomplete. An agent has no idea what the return value looks like, what constitutes a valid task, or what scoping is applied. The description is inadequate for a tool with two required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (taskId and contactId) documented as 'Task Id' and 'Contact Id'. The description adds no additional meaning, but the baseline of 3 applies because the schema fully explains the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Task' is essentially a tautology of the tool name. It lacks any specificity about what kind of task, what resource it operates on, or how it differs from sibling tools like contacts_get_all_tasks. An agent cannot distinguish this from other task-related tools without reading the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, context, or exclusions. The sibling list includes similar tools like contacts_get_all_tasks and contacts_delete_task, but the description provides no decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds no additional behavioral context. It does not disclose side effects (e.g., what happens when completed is set to false), permissions, or the exact scope of the update. Since annotations are present, the burden is lower, but the description still contributes nothing 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.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified rather than concise. A single sentence that adds no information is not efficient; it is a placeholder. There is no front-loading of critical scoping or usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three required parameters and no output schema, the description fails to provide essential operational context. An agent cannot infer the meaning of the 'completed' flag, the relationship between contactId and taskId, or the expected behavior of the operation. The description is inadequate for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 67% description coverage (taskId and contactId have 'Task Id' and 'Contact Id' labels, but no format or relationship info). The description adds no parameter meaning, failing to clarify the role of 'completed' (e.g., accepted values, effects) or how taskId relates to contactId. The description does not compensate for the missing parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Task Completed' is a tautology that merely restates the tool's name. It provides no specificity about what 'update' means in this context or what 'task completed' refers to, and does not differentiate from the sibling tool 'contacts_update_task'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'contacts_update_task' or 'contacts_create_task'. No conditions, prerequisites, or exclusions are mentioned, leaving the agent without context on selection.
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?
The description adds no behavioral context beyond what annotations already specify. Annotations indicate it is a mutation (readOnlyHint false) and idempotent, but the description does not explain side effects, what fields change, or any constraints. No contradiction exists, but the description is content-free.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words, which is concise but grossly under-specified. It lacks any structure or elaboration, making it closer to a placeholder than a functional definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 required parameters, a complex details object, and no output schema, the description is completely insufficient for an agent to understand how to invoke it correctly. The description contributes nothing toward the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 40% schema description coverage, the description needed to compensate for ambiguous parameters, but it provides nothing. The nested 'details' object is complex and the 'type' enum is central, yet none of this is explained in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Action' states a verb and a resource, but it is essentially a restatement of the tool name. It provides no detail about what kind of action is updated, what the action represents, or how it differs from similar siblings like conversation_ai_create_action or voice_ai_update_action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios, or exclusions. The agent receives no information about whether this is for modifying existing conversation AI actions or something else.
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?
Annotations already indicate this is a write operation (readOnlyHint=false), so the description adds no new behavioral context. It does not disclose side effects, required authentication, rate limits, or what happens to existing settings. It merely repeats the verb 'Update' without any additional transparency, failing to complement 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which might be seen as concise, but it is under-specified rather than concise. It does not earn its place as it adds no value beyond the tool name. The single phrase is front-loaded but lacks any substantive content, so it fails the 'every sentence earns its place' test.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 required params, nested object, no output schema), the description is grossly incomplete. It provides no explanation of the tool's purpose, how the parameters relate, or what the expected behavior is. An agent has no information to correctly invoke this tool beyond the raw schema, which is also sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameters (agentId, actionIds, followupSettings), but it provides no information about them whatsoever. The nested followupSettings object has some descriptions in the schema, but the description itself offers no clarity on how these should be used or their meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Followup Settings' is essentially a restatement of the tool name, lacking any description of what followup settings are, what updating them entails, or how it differs from sibling tools like conversation_ai_update_action or conversation_ai_update_agent. It provides no specific verb+resource detail beyond the name, making it a borderline tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains no guidance on when to use this tool versus alternatives. It does not mention the context (conversation AI, agent, actions) nor any prerequisites or conditions that would route an agent here over other update tools. There is no exclusions or alternatives mentioned.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the create intent is known. However, the description adds no behavioral context beyond that—such as side effects, defaulting of locationId, or what the response will contain. It contributes zero additional 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single fragment and technically concise, but it is under-specified rather than efficiently structured. It provides no usable content and lacks any logical organization, so it does not earn credit for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, only 20% schema coverage, and no output schema, the description is critically incomplete. It fails to explain what the tool creates, how to use it, or any defaults or constraints. An agent cannot correctly invoke this tool from this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema description coverage, the description must compensate by explaining key parameters like name, dataType, position, or placeholder. It does not mention any parameters at all, leaving required fields like dataType completely undocumented. This is a severe gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Custom Field' essentially restates the tool name with no additional specificity. It fails to convey that this tool is scoped to locations (as opposed to the sibling custom_fields_create_custom_field) or to clarify what makes it distinct. It is vague and provides no actionable information about what kind of custom field is created or for which models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance whatsoever on when to use this tool versus alternatives like custom_fields_create_custom_field. There is no mention of prerequisites, location context, or conditions that would select this tool. The description is completely silent on usage context.
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?
The description provides no behavioral details beyond the bare action. Annotations are sparse (no readOnly, no destructive, openWorld true), so the description should explain effects, but it doesn't. It fails to disclose whether followers are appended, replaced, validated, or any side effects, leaving the agent without critical behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which might seem concise, but it is under-specified. It merely repeats the tool name in a slightly shorter form and omits essential information. It does not front-load useful content and does not earn its place as a helpful summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and sparse annotations, the description is critically incomplete. An agent would not know what 'followers' are, how they are added, or any constraints or side effects. The description does nothing to fill the gaps left by the schema and annotations, making it inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds nothing to the parameter semantics. The schema provides a basic description for 'id' but none for 'followers', and the description 'Add Followers' does not clarify what constitutes a follower, the expected format, or the relationship to the opportunity. The description fails to compensate for the incomplete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add Followers' is vague and does not specify the resource (opportunity). It is essentially a shorter version of the tool name without stating that it affects opportunities. It does not differentiate from sibling tools like contacts_add_followers_contact, leaving ambiguity about which entity the followers are added to.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like opportunities_remove_followers_opportunity or contacts_add_followers_contact. The description offers no context about prerequisites, conditions, or situations where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no extra behavioral context whatsoever—nothing about return structure, pagination, limits, or any side effects. It provides zero 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is severely under-specified—two words with no substantive content. This is not conciseness but a lack of specification. It does not front-load any useful information because there is none. Minimal length alone does not earn points when it omits essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 20 parameters, one required, and no output schema, the description is completely inadequate. An agent would be unable to determine what filters are available, what data is returned, how pagination works, or any other operational details. The description offers no assistance for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 70%, meaning some parameters lack descriptions (q, page, order, country, assigned_to). The description does not compensate for these gaps nor add any insight into parameter relationships. While the schema covers most parameters, the description contributes nothing to parameter understanding, so the score is low despite partial schema help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Opportunity' is a tautology of the tool name 'opportunities_search_opportunity'. It merely restates the verb and object without adding any detail about what the search returns, scope, or filters. It fails to distinguish this from sibling search tools like opportunities_search_opportunities_advanced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to use this tool versus alternatives. It does not mention the more advanced sibling search (opportunities_search_opportunities_advanced) nor provide any context such as 'use for simple searches' or 'use when you need to filter by status.' No exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no behavioral traits. It never states that the operation modifies the app's capability settings, what side effects occur, or whether it requires special permissions. The annotations do indicate non-readonly, non-destructive, idempotent behavior, but the description adds no context beyond that, and it does not explain what 'update capabilities' actually entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, this is under-specification, not conciseness. It is a single noun phrase with no structure, no sentence, and no separation of concerns. It does not earn its place for information content and is effectively a placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and no output schema, the description should explain what the tool does, what 'update capabilities' means, and what the expected outcome is. It provides none of this. An agent cannot correctly determine how to invoke or interpret the result from this definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, including the required 'supportsSubscriptionSchedules'. The description adds no further meaning; it does not reference or clarify any parameter relationships. Since the schema already documents the parameters adequately, the description does not need to compensate, but it adds zero value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Custom-provider marketplace app update capabilities' is a noun phrase that almost exactly repeats the tool name. It provides no action verb, no explicit resource, and no clarification of what 'capabilities' means. It is a tautology and does not distinguish the tool from any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool, what conditions warrant it, or which alternatives exist. It does not mention any exclusions or comparisons to related payments tools. An agent has no context to select it over other payment operations.
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?
The description provides almost no behavioral detail beyond 'attach'. It does not disclose side effects, permissions (e.g., whether Facebook OAuth is required), whether the operation is reversible, or what happens to existing attachments. With no annotations providing meaningful safety context (readOnlyHint=false, but no detail), the description carries the full burden and fails to meet it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, but this is under-specification rather than effective conciseness. It consists of a single vague phrase with no structure, no front-loaded key information, and no separation of purpose vs. instructions. Every sentence should earn its place, but here there are no useful sentences at all.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and a non-trivial operation (attaching Facebook pages), the description is woefully incomplete. It does not explain what 'attach' results in, what data is required for the type object, any expected result, or error conditions. An agent cannot correctly invoke this tool based on the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds nothing about the 7 parameters. Schema coverage is only 43% (only accountId and locationId have descriptions), and the description does not clarify the purpose of name, type, avatar, originId, or companyId. The type parameter is an open object with no explanation. Since the description is the primary source of meaning for these undocumented fields and is empty, this is a critical failure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Attach facebook pages' states a verb and a resource but is ambiguous about the target of the attachment and the context. It doesn't clearly distinguish from sibling tools like 'social_media_posting_attach_instagram_page_group' beyond the explicit 'facebook' keyword, and it does not specify what the attachment is for or how it relates to the account. This is barely more informative than the tool name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many sibling social media posting tools. No mention of prerequisites like OAuth, no indication of when it is appropriate to attach pages, and no alternatives suggested. An agent has no basis to choose this tool over its siblings.
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?
Annotations indicate readOnlyHint=false (mutation), openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds nothing beyond these hints—it does not explain the mutation's effects, required authentication, whether existing profile associations are overwritten, or what happens on the Twitter side. Since annotations are minimal, the description carries the burden of behavioral disclosure, and it fails entirely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but it is so under-specified that it does not serve its purpose. While conciseness itself is fine, the content is insufficient to guide an agent. It is not 'appropriately sized' because it omits essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, no output schema, and no nested objects, the tool's context is not simple. The description provides no information about what the tool does beyond the verb 'attach', what the attached profile represents, how it relates to the account/company/location, or what a successful call returns. It is completely inadequate for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only accountId, companyId, locationId have descriptions). The description does not explain any of the 9 parameters (name, avatar, originId, username, verified, protected, etc.), nor does it clarify the purpose of the required accountId. With low schema coverage, the description should compensate, but it provides no parameter semantics at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('attach') and a resource ('Twitter profile'), but it adds almost no information beyond what the tool's name already conveys. It does not specify what 'attach' means in this context, which fields are relevant, or how it differs from sibling attach tools like social_media_posting_attach_facebook_page_group. It is nearly a tautology of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the similarly named sibling attach tools (e.g., attach_instagram_page_group, attach_linkedin_page_profile). No context is given about prerequisites, expected input sources, or scenarios where this tool is appropriate. The description provides zero usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation) and destructiveHint=false, but the description does not add any behavioral context beyond that. It does not mention required fields, potential side effects, authorization needs, or response expectations, which are important for a creation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than efficient conciseness. It lacks any structure or prioritization of important information, and the single phrase does not earn its place given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters (8 required), nested objects, and no output schema, the description provides virtually no context for an agent to correctly invoke the tool. The two-word description is nowhere near sufficient for such a complex creation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only 27% description coverage, and the description adds no parameter meanings. Many parameters (e.g., role, type, email, password) are not described in either schema or description, and the description does not compensate for the low coverage. An agent would have to infer correct values with little guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create User' is a tautology of the tool name 'users_create_user' and provides no additional specificity about what creating a user involves or what the tool's exact scope is. It fails to distinguish the tool from other user-related operations like update or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as users_update_user or users_filter_users_by_email. No context, prerequisites, or exclusions are mentioned, leaving the agent without direction on selecting this tool correctly.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds virtually no behavioral context, such as whether it returns a single entity or a list, or how over-fetching works. This is a bare minimum that fails to build on 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is not conciseness but under-specification. A useful definition would front-load the purpose and key parameters; this one gives the agent nothing actionable and is far too terse to be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and a large set of sibling tools, the one-phrase description is grossly inadequate. It does not explain which parameters are required for different entity types, what the response looks like, or how it fits within the broader ad_manager_fb set – leaving an agent unable to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 9 parameters are individually documented. The description itself provides no additional meaning about parameter relationships, such as which identifiers combine with entityType, or the purpose of flags like 'fetchAll' and 'next' – the schema already does the heavy lifting, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get entities' is a direct restatement of the tool name, providing no specific verb-resource detail or entity types. It doesn't mention that it retrieves campaign, adset, or ad entities from Facebook ads, nor does it distinguish itself from the many sibling get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is given. The description does not explain when to choose this generic tool over more specific ones like ad_manager_fb_get_campaign or ad_manager_fb_get_ad_account, nor does it mention any prerequisites, exclusions, or pagination behavior.
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?
The description adds no behavioral traits beyond what annotations already declare (readOnlyHint: false, idempotentHint: true). It does not explain what an upsert does in practice—whether it creates or updates, what side effects occur, or any requirements. Since annotations provide minimal coverage and the description adds nothing, this is a complete failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), but it is under-specified to the point of being uninformative. This is not effective conciseness but rather a lack of meaningful content. It fails to provide even a complete sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with 16 parameters, no output schema, and a non-trivial operation (upsert). The description gives no context about the create/update semantics, required parameters (campaignId, adsetId) beyond what the schema already lists, or any operational details. The description is woefully incomplete for an agent to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has descriptions for all 16 parameters, providing 100% schema coverage. The description itself contributes nothing to parameter understanding. Per the rubric, with high schema coverage the baseline is 3, and no additional value is added, so 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert ad' is a tautology of the tool name 'ad_manager_fb_upsert_ad'. It restates the verb and resource without adding any specificity, and does not distinguish it from sibling tools like ad_manager_fb_upsert_adset or ad_manager_fb_upsert_campaign. The agent gets no insight into what an upsert entails or how this ad-specific tool differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any conditions, prerequisites, or exclusions. The description is a single verb phrase with zero contextual information.
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?
Annotations provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false, indicating a non-read, non-destructive, non-idempotent operation. The description adds zero behavioral detail beyond what the annotations already imply—no mention of side effects, authentication requirements, or rate limits. It simply repeats the operation name without enriching the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse ('Upsert assets'), which is technically concise but grossly under-specified. It lacks even a sentence that introduces the asset types or the conditional payload structure. While brevity is valuable, this is not appropriately sized—it omits essential context rather than efficiently conveying it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested payload with many condition-dependent fields, yet the description provides no high-level guidance on what assets are supported, how to choose the correct type, or what the upsert behavior entails (create vs update). With no output schema, the description should at least summarize expected outcomes, but it is entirely absent. The lack of any context makes the tool nearly impossible to use correctly without deep schema inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter has a description in the input schema. The overall description adds no parameter-specific meaning; it doesn't clarify relationships between type and payload or any conditional requirements. Given the high schema coverage, the baseline of 3 is appropriate; the description neither enhances nor detracts from schema clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert assets' is a tautology of the tool name, restating the verb and resource without any specificity. It doesn't clarify what kind of assets (call, sitelink, lead form) or the platform, leaving the agent to infer from the name alone. It fails to distinguish the tool from sibling tools like ad_manager_google_upsert_campaign or ad_manager_fb_upsert_ad.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of conditions for creating vs updating, prerequisites like integration authorization, or when to prefer ad_manager_google_get_assets for retrieval. The description is completely silent on usage context.
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?
The description adds no behavioral context beyond the annotations. Annotations indicate readOnlyHint=false and destructiveHint=false, but the description does not disclose side effects, required permissions, idempotency concerns, or any consequences of creation. It offers no value beyond generic labels.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified rather than concise. It consists of two words that add no information. While it is not verbose, it fails to earn its place because it merely repeats the tool name. True conciseness would pack value into few words; this lacks substance entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, a nested version object, no output schema, and multiple sibling create tools, the description is severely incomplete. An agent cannot be created correctly without knowing the structure, required fields, or expected behavior. The description offers no guidance whatsoever.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 92%, so the baseline is 3. The description itself adds no parameter insight, but the schema already documents all properties adequately. Since no additional meaning is needed and none is provided, the baseline holds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Agent' is a tautology that merely restates the tool name. It fails to specify what an agent is in this context, what creating one entails, or how it differs from sibling tools like conversation_ai_create_agent and voice_ai_create_agent. No differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives. Multiple create-agent tools exist across domains (agent_studio, conversation_ai, voice_ai), but the description does not mention any selection criteria, prerequisites, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false, etc.), the description discloses nothing about side effects, required permissions, or idempotency. For a creation tool, critical behavioral context like validation rules, automations triggering, or slot availability checks are entirely absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely under-specified, not concise. While brevity is beneficial, a two-word tautology fails to convey any useful intent or usage context, making it insufficient for an agent to act correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 parameters, no output schema, and a mutating operation, the description is grossly incomplete. It provides no info about required context (e.g., how to obtain calendarId/contactId, time format, recurrence, or concurrency rules), leaving the agent without essential guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 94%, so the schema provides robust parameter documentation. The description adds no parameter information, but per the baseline for high coverage, this is acceptable; however, it does not compensate for any gaps the schema might have.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create appointment' is a pure tautology, restating the tool name without any additional specificity. It does not distinguish from siblings like calendars_edit_appointment or calendars_get_appointment, offering no unique resource scope or behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context about prerequisites, selection criteria, or exclusions is provided, leaving the agent to infer entirely from the name.
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?
Annotations indicate a non-read-only (readOnlyHint=false) and idempotent (idempotentHint=true) operation, but the description adds no contextual behavior. It does not disclose what happens to the slot, whether it affects appointments, or any restrictions (e.g., that calendarId and assignedUserId are mutually exclusive). The description provides zero behavioral disclosure beyond the minimal action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than efficient conciseness. It lacks any structure, front-loading, or prioritization of key information. A well-crafted description would at least state the resource and key constraints in a clear opening sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters and no output schema, the description is completely inadequate. It fails to explain what a Block Slot is, the meaning of the parameters (even though schema provides some), the effect of updating, or any side effects. An agent would have no confidence in how to call this correctly. The lack of output schema makes it worse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all 7 parameters with at least basic descriptions (e.g., 'Either calendarId or assignedUserId can be set, not both.'). Since schema coverage is 100%, the description need not repeat parameter details. However, the schema descriptions are terse and the tool description adds nothing, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Block Slot' is a tautology that simply restates the tool name. It fails to define what a Block Slot is, what updating it entails, or how it differs from sibling tools like calendars_create_block_slot or calendars_get_blocked_slots. No specific verb-resource clarity beyond the obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, such as needing an existing block slot to modify, or how it relates to creating or deleting slots. The agent receives no direction on selecting this tool among the many calendar siblings.
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?
Annotations declare readOnlyHint=false, indicating a mutation, and openWorldHint=true, but the description adds nothing about side effects, required authentication, or state changes. It does not contradict the annotations, but it fails to add any behavioral context. For a write operation, the description should at least hint at the consequences or prerequisites, but it is silent. Since annotations exist, the bar is lower, yet the description offers zero additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It fails to convey any useful information that would help an agent. Every word is wasted because it merely restates the obvious. A single phrase without context or examples cannot be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, a multi-step upload workflow (initiate then complete), and no output schema. The description omits critical context such as how uploadId and filePath are obtained, any ordering constraints, or what the response indicates. Without this information, an agent cannot correctly invoke the tool in the intended sequence. The description is far from complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (uploadId, filePath, conversationId, filename, locationId) has a descriptive comment. The tool description itself adds no parameter-level detail, but with full schema coverage, the baseline of 3 is appropriate. The description does not hinder understanding of parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Complete file upload' is a tautology of the tool name 'conversations_complete_file_upload'. It restates the name without specifying the verb, resource, or any distinguishing detail. There is no context about what the upload completion entails, how it relates to the initiate step, or how it differs from sibling tools like 'conversations_add_message_attachments'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description gives zero context about prerequisites (e.g., needing an uploadId from a prior initiate call), the typical workflow, or exclusions. An agent cannot determine the appropriate invocation scenario from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It does not disclose that it returns matching conversations, supports pagination, or any other operational characteristics, leaving agents with no clue about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise but under-specified. For a tool with 21 parameters, a single phrase is not appropriately structured or informative; it fails to guide the agent on how to interpret or use the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (21 parameters) and lack of an output schema, the description provides no useful context about what the tool does, what it returns, or how to use it effectively. An agent would be completely lost.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 21 parameters (100% coverage), so the description adds no additional meaning. The high schema coverage sets a baseline of 3, and the description does not supplement it with greater context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Conversations' is a tautology of the tool name, providing no specific verb-resource detail, no indication of what is searched or returned, and no differentiation from sibling search tools like conversations_get_conversation or contacts_search_contacts_advanced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that it is a search/list operation, suggest typical filter combinations, or reference more specific tools like conversations_get_conversation for single-conversation retrieval.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's not a read-only or destructive operation. However, the description adds no further behavioral context—no mention of side effects, conditional requirements, or consequences. It fails to disclose anything 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It lacks any structure or useful content, and while it is brief, it does not earn its place by conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has a complex input schema with nested objects, required conditional fields (e.g., legal_reason required for resub actions), and multiple subscription action types. The description provides no context about these requirements, making it completely inadequate for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning every parameter has a description in the schema itself. The description adds no additional semantic meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is merely a noun phrase "User Subscription Change" that restates the tool name without a verb or resource. It does not explain what the tool does, and it is indistinguishable from the title itself—a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. Sibling tools like conversations_get_contact_unsubscription_status or conversations_create_custom_subtype exist, but the description says nothing about the appropriate context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry minimal behavioral information (readOnlyHint=false, destructiveHint=false). The description adds no behavioral disclosure about side effects, such as whether an email is sent, whether it is a verification lookup, or any rate limits or authentication requirements. The description fails to carry the burden that annotations leave uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It lacks even a verb phrase and provides no structured information. While it is not verbose, it is not appropriately sized because it omits essential content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and only three parameters, but the description is still insufficient. It does not explain what 'verify' means, what happens when called, what the return value is, or any operational constraints. An agent would have to guess the tool's behavior entirely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so per the rubric the baseline is 3. The description adds no parameter-specific meaning, but the schema already documents all properties adequately for an agent to understand them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Email Verification' is essentially a label that restates the tool name without specifying the action. It does not say what the tool actually does (e.g., sends a verification email, checks email validity), and it provides no distinguishing information from the vast sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, when not to use it, or what alternatives exist. The description gives no context about the intended use case or prerequisites.
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?
The description discloses no behavioral traits beyond what the annotations already state (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It adds no context about return format, errors, or side effects, so it fails to contribute any additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but not concisely informative; it is under-specified and contains a grammatical error ('an template'). It lacks substantive content, so it is not a good concise description – it is minimal to the point of being useless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET tool, the description is incomplete: it does not state what is returned, whether the call can fail, or any related context. With no output schema and only the name, the agent has insufficient information to know what to expect from calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so baseline is 3. The tool description itself adds nothing about parameters, but given high schema coverage, it does not need to compensate. However, it also does not clarify the semantics of templateId/altId/altType, so it earns only the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get an template' is essentially a tautology of the tool name and does not specify what a template is, what it retrieves, or how it differs from sibling tools like invoices_list_invoice_templates or invoices_create_invoice_template. It provides no functional clarity beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when to call it, or how it relates to listing or creating templates, leaving the agent without any selection context.
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?
The description adds no behavioral information beyond what the annotations already state. Annotations indicate readOnlyHint=false and destructiveHint=false, but the description reveals nothing about side effects, required permissions, or what happens on execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but not in a positive way—it is under-specified. One vague sentence with grammatical errors fails to provide any useful structure or front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with a complex nested schema and no output schema, the description is entirely inadequate. An agent would have no idea what 'scheduling an invoice' entails, what the required scheduleId and liveMode mean semantically, or what success looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameters (scheduleId, altId, altType, autoPayment). The description contributes nothing, but the baseline of 3 is appropriate since the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Schedule an schedule invoice' is a tautology that merely restates the tool name without any additional information. It fails to distinguish this tool from its siblings like invoices_create_invoice_schedule or invoices_update_invoice_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, under what circumstances, or how it differs from alternative invoice scheduling tools. The description provides no context for selection.
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?
Annotations declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false, but the description adds no behavioral context beyond that. It doesn't explain side effects, required permissions, or error scenarios, so it fails to add 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is under-specification, not conciseness. The description gives no structured information and fails to front-load any useful detail. It is effectively as minimal as possible without being empty.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 27 parameters, nested objects, and no output schema, the description offers no context about return values, required inputs, or the update workflow. It is completely inadequate for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 93% (high), so the baseline is 3. The description doesn't add any parameter semantics beyond what the schema already provides, so it neither improves nor harms parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Estimate' is a tautology that merely restates the tool name. It says nothing about what an update entails, which fields are affected, or how it differs from the many sibling invoice/estimate tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives like invoices_create_new_estimate or invoices_update_invoice. No context, no exclusions, no prerequisites.
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?
The description provides zero behavioral information beyond what annotations already declare (readOnlyHint, idempotentHint, destructiveHint). It does not disclose defaulting behavior for locationId, the fact that the 'id' parameter can be a field key, or any response characteristics. With no added context, the description fails to leverage the safety annotations to add meaningful detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Get Custom Field'), which could be seen as concise, but it is under-specified rather than effectively concise. It lacks essential details that would help an agent understand the tool's purpose or invocation. A single phrase that merely restates the name does not earn credit for conciseness because it omits required substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and minimal annotations, the description should explain what a custom field is, what the return value represents, and how it differs from sibling tools like 'locations_get_custom_fields' or 'custom_fields_get_custom_field_by_id'. None of this context is provided, leaving the agent with insufficient information to select or invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters 'id' and 'locationId' have explicit descriptions in the schema (id: 'Custom Field Id or Field Key...', locationId: 'Location Id Defaults to GHL_LOCATION_ID when omitted'). The tool description adds no parameter semantics, but per the rubric, with high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Custom Field' is essentially a tautology of the tool name 'locations_get_custom_field'. It does not specify the resource type (location), the scope, or the nature of the custom field. The verb 'Get' is present, but the resource is vague ('Custom Field' could refer to any custom field in the system). Without context, an agent cannot distinguish this from siblings like 'locations_get_custom_fields' or 'custom_fields_get_custom_field_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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention the singular/plural distinction, the difference between locations_ and custom_fields_ namespaces, or any preconditions. An agent has no idea whether this is the right tool for retrieving a single custom field by ID or key, or whether a different sibling should be used.
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?
Beyond the annotations (readOnlyHint false, destructiveHint false, openWorldHint true), the description adds no behavioral context. It does not disclose what sending entails, whether it triggers emails, updates records, requires permissions, or any side effects. Since annotations do not fully cover safety (readOnlyHint false implies mutation), the description should provide more detail but remains silent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which could be seen as concise, but it is under-specified rather than efficiently worded. A concise description should pack meaningful guidance into few words; 'Send template' provides almost no actionable information. It is a fragment, not a well-structured sentence, and every word does not earn its place because it conveys nothing useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, 3 required, and no output schema, the description is completely inadequate. It lacks any explanation of what the tool does, how the parameters interplay, expected outcomes, or any context that would let an agent call it correctly. The openWorldHint annotation suggests broader behavior not described here, leaving the agent guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with basic descriptions like 'User Id', 'Contact Id', etc. The description does not add any meaning beyond these trivial labels. While baseline is 3 for high coverage, the description's failure to explain the relationship between parameters (e.g., templateId, userId, contactId) or how they are used keeps it at baseline. It neither helps nor hurts parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send template' is a near-tautology, merely restating the tool's name without clarifying what sending a template does, to whom, or in what context. It fails to distinguish this tool from its sibling 'proposals_send_documents_contracts' which also sends documents/contracts. No resource or actual outcome is described.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as proposals_send_documents_contracts or proposals_list_documents_contracts_templates. There is no mention of prerequisites, conditions, or scenarios where this specific template-sending tool is appropriate.
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?
The description does not disclose any behavioral traits beyond the annotations. It does not state whether the operation is asynchronous, what side effects occur, or what the response looks like. Even though annotations indicate a mutating action (readOnlyHint=false), the description adds no context about what 'finalize' actually does, leaving the agent with no behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but this is under-specification rather than thoughtful conciseness. It lacks structure and does not front-load any useful information. It is a single clause that adds no value beyond the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description is entirely inadequate. It fails to explain what 'finalize' means in the context of CSV posting, what the CSV id refers to, or how this fits into the overall social media posting workflow. An agent has no clue when to invoke this tool or what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so each parameter (id, userId, locationId) already has a description. The tool description does not add any additional meaning or context to the parameters, but the baseline is 3 because the schema covers them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Start CSV Finalize' is essentially the tool name rephrased. It does not state what 'finalize' means, what resource it acts on, or what the outcome is. It is a tautology that provides no distinguishing information from the many sibling social_media_posting_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like social_media_posting_delete_csv or social_media_posting_get_csv_post. There is no mention of prerequisites, workflow context, or conditions that would trigger this tool.
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?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a mutating but non-destructive operation. The description adds no behavioral context beyond the name, such as partial update semantics, required agent existence, or side effects. It does not contradict annotations, but it provides zero value in explaining behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, but it is under-specified rather than efficiently written. Two words that only repeat the tool name do not earn their place; they fail to convey functional meaning. It is not a structured description that aids comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 20 parameters and no output schema, a two-word description is wholly inadequate. An agent has no way to know what the tool does, what inputs matter, or what to expect as a result. The description is grossly incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 20 parameters fully described in the input schema. The description adds no parameter information, but per the baseline for high coverage, a score of 3 is appropriate. The schema does the heavy lifting here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Patch Agent' is a tautology, essentially restating the tool name without providing a verb or resource context. It does not state that this modifies an existing voice AI agent via partial updates, nor does it distinguish itself from siblings like voice_ai_create_agent or voice_ai_update_action. The purpose is entirely unclear from this description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that this is the update path for existing agents, nor does it reference any preconditions or differences from create/delete/get operations. An agent selecting a tool would have no idea this is for patching an existing agent.
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?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the destructive nature is known. However, the description adds zero behavioral context – it does not mention that the deletion is permanent, whether any related resources are affected, or if any confirmation is needed. Since the description provides no added value beyond the annotations, it fails to 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a short two-word phrase, which is concise and avoids fluff. However, it is not a well-structured sentence and provides no meaningful structure to guide the agent. It is appropriately brief but under-specified, so it earns a middle score – not wasteful, but not adequately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, one required, and no output schema, the description is grossly incomplete. It does not explain what an 'agent' is in this context, how to identify one (agentId), or any side effects of deletion. The absence of any contextual guidance makes it nearly impossible for an agent to use this tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only describes locationId (defaults to GHL_LOCATION_ID), while agentId and source have no descriptions. The description 'Delete Agent' does not clarify what agentId refers to, how to obtain it, or the role of source. With schema coverage at only 33%, the description needed to compensate but instead adds nothing, leaving the most critical parameter (agentId) undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Agent' is essentially a restatement of the tool name 'agent_studio_delete_agent' – it adds no new information about the resource or scope. It states the verb and resource but does not distinguish from other agent_studio tools beyond the obvious deletion action, making it a tautology rather than a clarifying statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to use this tool versus alternatives, no prerequisites, and no context about agent deletion workflows. There is no mention of required permissions, related operations like agent creation or execution, or scenarios where deletion should be avoided. The agent is left to infer usage purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so a mutating operation is expected, and destructiveHint=false. The description adds no further behavioral detail—no mention of side effects, authentication requirements, or conditions. It is consistent with annotations but adds no value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, this is under-specification rather than conciseness. A single vague phrase does not front-load any useful information. For a tool with 4 required parameters and a complex nested details object, this is grossly insufficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested details, multiple action types, enums) and lack of output schema, the description is wholly incomplete. An agent lacks critical context about action types, required details per type, or any return behavior. Nothing an agent needs to call it correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only the details object has a description). The description does not explain any parameter: agentId, type, name, or details. With low schema coverage, the description should compensate, but it provides zero parameter semantics, leaving an agent to guess what values are expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Attach Action to Agent' is vague about the operation. It uses a verb ('Attach') but doesn't clarify that this creates a new action, nor does it specify the action types or the relation to an agent. It doesn't distinguish from similar sibling tools like conversation_ai_create_agent or voice_ai_create_action, and could be misinterpreted as attaching an existing action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, scenarios, or exclusions. An agent has no idea when to choose this over conversation_ai_update_action or voice_ai_create_action, or how it differs from creating an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only, not idempotent, and not destructive. The description adds nothing beyond the name, failing to disclose side effects (e.g., that it creates a persistent redirect that may affect traffic), permission requirements, or any operational nuances. With annotations already covering the basic safety profile, the description offers no additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
A two-word phrase is not conciseness; it is under-specification. The description is too short to convey anything useful and fails to front-load important details. It provides no structure or helpful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a creation tool with 5 parameters, no output schema, and no explanation of what a redirect is or how the tool behaves. An agent has almost no information to correctly invoke it beyond guessing parameter types. The description is completely inadequate for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only locationId has a description). The description does not explain any of the parameters, such as what 'action' values mean, how 'target' is used, or the format of 'path'. With such low schema coverage, the description was expected to compensate, but it provides zero parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Redirect' states the action and resource, but it essentially repeats the tool name. It provides no details about what a redirect actually is, what it does, or how it differs from sibling tools like funnels_update_redirect_by_id or funnels_delete_redirect_by_id. This is vague and lacks any distinguishing context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever on when to use this tool versus the other funnel redirect tools. No mention of prerequisites, typical use cases, or conditions that would make this tool preferable. The description is just a bare phrase with no context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description does not need to restate that it's a write operation. However, the description adds no behavioral context beyond that: it does not mention what happens to existing data, whether updates are partial or full replacements, or any side effects. With openWorldHint=true, the description should clarify external interactions but remains silent. It does not contradict annotations, but provides minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It contains a single phrase that adds no distinct information. The description does not front-load any useful context or structure to help an agent parse the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 15 parameters, nested objects, no output schema, and multiple related siblings. The description is entirely inadequate for an agent to understand how to correctly call the tool. It provides no context about required fields, how schedule updates work, or what the expected result is. The description fails to cover even the most basic context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, meaning many parameters lack descriptions in the schema. The description 'Update schedule' provides no additional meaning for any parameter. It fails to compensate for the low schema coverage by explaining the purpose or relationships of fields like 'items', 'schedule', or 'discount'. An agent would have to guess the semantics of most required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update schedule' is a near-tautology of the tool name 'invoices_update_invoice_schedule'. It restates the verb and resource without adding any specificity about what an invoice schedule is, what updating entails, or what fields are affected. An agent cannot distinguish this from the many other schedule-related invoice tools (e.g., 'invoices_create_invoice_schedule', 'invoices_schedule_invoice_schedule') based on this description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, when to update versus create or schedule, or any exclusions. The agent is left to infer usage entirely from the schema, which is unhelpful given the number of related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, which signal safety, but the description adds no behavioral context beyond that. It does not mention what the tool returns (e.g., a list of tasks), how pagination works, or any constraints (e.g., that locationId defaults to the authenticated location). Given the annotations already cover read-only behavior, the description's complete lack of additional behavioral disclosure keeps this low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified, not concise in a useful way. It is a three-word fragment that provides no information while consuming space. Effective conciseness means every sentence earns its place; here, the entire description fails to convey any meaningful instruction, making it inadequate rather than economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and no output schema, the description is woefully incomplete. It does not explain the return format, the semantics of the filters, or how the tool fits into the broader workflow. The annotations cover safety but not functionality, leaving an agent without enough context to call the tool correctly or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 8 parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds no parameter semantics beyond the schema, which is acceptable since the schema is comprehensive. However, it could have added contextual meaning (e.g., that 'query' is a free-text search), but it does not, so no bonus is granted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Task Search Filter' is a vague fragment that restates the tool name 'locations_task_search' without adding any specific action, resource, or scope. It does not say what tasks are being searched (e.g., for contacts, locations) or what the filter does, and it fails to distinguish this tool from other search tools like contacts_search_contacts_advanced or opportunities_search_opportunities_advanced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternative search tools. The description provides no context about scenarios (e.g., searching tasks by query, filtering by completion status) or exclusions. An agent gets no help in deciding to choose this over the many sibling search tools available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does disclose the authentication requirement ('requires an agency-level token, not a location PIT'), which is a useful behavioral detail. However, the core action described is wrong (update vs. generate), making the overall behavioral disclosure misleading. It adds some value but is fundamentally inaccurate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence), but brevity is not an asset when the content is inaccurate. It fails to be appropriately structured for the tool's actual function, and the token requirement is unrelated to the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a payment-link generation tool, the description is completely inadequate. It says nothing about generating links, what the response contains, or any prerequisites beyond the token. The stated action is for a different operation, leaving the agent without any useful context for the real task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all four parameters with 100% coverage, so the description adds no parameter information. Moreover, the description's mention of 'Update SaaS subscription' has no relation to the actual parameters (subscriptionId, customerId, companyId, locationId), and it misleads about what the parameters are for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update SaaS subscription' which directly contradicts the tool name 'saas_api_generate_payment_link'. This is misleading; an agent would think this tool updates subscriptions rather than generating payment links. The description fails to convey the actual purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The only aside about token requirements is a credential note, not usage context. There is no mention of scenarios, exclusions, or comparison with related saas_api tools.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds nothing beyond the tool name—it does not explain that this is a read operation that returns agent configuration, nor does it disclose any side effects, authentication needs, or response behavior. No added context to justify a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single two-word phrase. While concise, it is under-specified to the point of being unhelpful. It does not front-load any useful information that would help an agent decide or execute correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters and a simple read operation, the minimal description might suffice technically, but it omits the return format and any behavioral notes. Despite the high schema coverage, an agent gets no confidence about what the response contains or how to interpret the result, especially given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both agentId and locationId have inline descriptions. The tool description itself adds no parameter semantics, so per the rubric the baseline 3 applies. It correctly relies on the schema, but offers no extra clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is just "Get Agent" — a tautology of the tool name. It does not specify what agent is fetched, by what identifier, or what the returned data represents. It also fails to distinguish itself from siblings like voice_ai_get_agents (plural) or conversation_ai_get_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. An agent cannot tell whether to pick this over voice_ai_get_agents for listing, or whether it is for retrieving a single agent by ID. No context or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete ad' is consistent but adds no new behavioral context. It does not mention permanence, cascading effects, permission requirements, or any side effects beyond the bare action. With annotations carrying the safety profile, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It omits necessary context that a destructive operation with an ambiguous resource identifier requires. The brevity does not serve the agent's decision-making.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema and a description that only says 'Delete ad', the agent lacks essential information: what an 'ad' is in this context, what happens on success, whether the deletion is permanent, and what the effects are. The description is inadequate for the complexity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description says nothing about the parameters. The input schema covers only 50% of parameters with descriptions (locationId), while adId is undocumented. The description does not compensate for this gap, leaving the agent without guidance on what adId refers to or how locationId affects the operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete ad' states a verb and a resource, but it is essentially a restatement of the tool name 'ad_manager_fb_delete_ad'. It adds no distinction among the many sibling delete tools (e.g., delete_adset, delete_campaign, delete_ad_account), so an agent cannot tell which entity is being targeted beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context about prerequisites, whether a specific integration/account must exist, or when one might prefer a pause or update instead of delete. The description provides zero usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's a write operation (readOnlyHint false), not idempotent, and not destructive, but the description adds no behavioral context such as what happens to the source ad, whether a new ad ID is returned, or if any settings are excluded. The bar is lower due to annotations but the description still contributes nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is too terse – it's under-specification, not efficient conciseness. There is no explanation of scope, behavior, or parameters. While brevity is appreciated, this lacks critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and minimal annotations, the description is grossly inadequate. It doesn't say what happens after duplication, whether there are any constraints, how to handle errors, or what the expected result is. An agent has no confidence in calling this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the adId parameter at all. With 0% schema description coverage, the description must explain what adId refers to (e.g., 'the ID of the ad to duplicate') but it doesn't. The parameter is entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Duplicate') and resource ('ad'), which distinguishes it from duplicating campaigns or adsets, but it lacks any detail about what duplication entails—whether it creates a new separate ad, copies all settings, or returns a new ID. It is more informative than a pure tautology but still minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like upsert_ad, duplicate_adset, or delete_ad. No mention of prerequisites, the relationship to the original ad, or any caveats. An agent cannot infer when duplication is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish this as a read-only, idempotent, non-destructive operation, so no contradiction exists. However, the description adds no additional behavioral details such as pagination behavior, default date ranges, or result format. With no output schema, the description should at least hint at what the response contains, but it does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is under-specified and essentially repeats the tool name. It does not earn its place because it provides no unique information beyond the schema, making it more of a placeholder than a useful definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters, no output schema, and many similarly named siblings, this description is drastically incomplete. It gives no indication of what the tool returns, what list types are supported, or how it relates to other reporting tools, leaving agents without critical information to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, so the baseline is 3. The description does not add extra meaning to parameters like listType or campaignId, but since the schema is complete, no penalty is applied. The description neither clarifies nor conflicts with the parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get reporting list' is essentially a direct restatement of the tool name, providing no additional detail about what constitutes a 'reporting list' or how it differs from similar siblings like ad_manager_fb_get_reporting or ad_manager_google_get_reporting_list. It fails to specify the platform, scope, or nature of the list, making it a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus its many comparable alternatives, such as ad_manager_google_get_reporting_list or ad_manager_fb_get_campaign_reporting. The description offers no context, prerequisites, or exclusions, leaving the agent to guess which reporting list tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the annotations (readOnlyHint=false, destructiveHint=false), but it adds no behavioral detail beyond what the name implies. It fails to disclose side effects, whether pausing is reversible, or any permission requirements, despite openWorldHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It lacks essential information that could be conveyed in a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with two parameters and no output schema, the description is completely inadequate. It does not explain what pausing an ad entails, what state changes occur, or any expected outcomes, leaving the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. The schema covers only 50% of parameters (locationId has a description, adId does not), and the description adds nothing to help an agent understand what adId refers to or how it should be supplied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Pause ad' is essentially a tautology of the tool name. It states the verb and resource but provides no scope, context, or differentiation from similar tools like ad_manager_fb_pause_adset and ad_manager_fb_pause_campaign, which are siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as pausing an ad set or campaign, or resuming an ad. There is no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the agent knows the operation is safe to retry and non-destructive. The description adds nothing about side effects, prerequisites, or what happens on update vs create. With annotations present, the bar is lower, but the description still provides no 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), but this is under-specification rather than concise efficiency. It lacks essential detail and does not front-load useful information. It is not 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.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, a nested object, and no output schema, this description is completely inadequate. It does not explain what a conversion is in the Google Ads context, how the upsert behaves, or any prerequisites. The agent has to infer everything from the schema, which is insufficient for a complex write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and all parameters have descriptive text in the schema. The description adds no parameter-specific information, but since the schema fully documents parameters, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description "Upsert conversion" is a tautology that restates the tool name without adding any specific information. It does not specify what kind of conversion, which ad platform (Google), or how it differs from other upsert tools (e.g., ad_manager_fb_upsert_ad). An agent cannot distinguish this tool from many siblings based on this description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of use cases, prerequisites, or exclusions. The description gives no context about when an agent should select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. However, the description adds zero behavioral context—no mention of return format, error handling, or what 'agent' refers to. It provides no additional 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, this is under-specification rather than effective conciseness. The two-word description omits essential details, failing to use the description field to convey any useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters (one required) and no output schema, the description is completely inadequate. It does not explain what an agent is, how to obtain the ID, or what the response contains. An agent would have no clues on correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (locationId described). The description does not explain agentId, source, or how they relate, nor does it compensate for the missing schema documentation. It adds no parameter meaning whatsoever.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Agent' states a verb and resource but offers no differentiation from siblings like agent_studio_get_agents or the deprecated variant. It lacks specifics about what an agent is or the scope of the lookup, making it ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of needing an agentId or when to prefer this over agent_studio_get_agents, and no exclusions or context provided.
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?
The description adds no behavioral context beyond what the annotations already provide. Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, which already tell the agent it is a safe read operation. The description merely restates the action and does not disclose any additional behavior (e.g., side effects, required permissions, error conditions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one short sentence) but is under-specified rather than effectively concise. It provides no more information than the tool name itself, wasting the opportunity to add value. It is minimalism without substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the tool returns. It does not. It also fails to provide any context about the 'association key' concept, the purpose of the lookup, or any prerequisite conditions. For a tool with two parameters and no return specification, the description is utterly inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (only locationId has a description). The description does not clarify the key_name parameter at all, leaving the agent to guess its format or meaning. With one required parameter undocumented, this is a critical deficiency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get association key'), which distinguishes it from tools like associations_get_association_by_id or associations_get_association_by_object_keys by indicating it retrieves a key by its name. However, it does not explain what an 'association key' is, leaving ambiguity about the tool's exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, exclusions, or which sibling tools to prefer. The description is entirely bare, giving the agent no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which cover safety and idempotency. However, the description adds no additional behavioral context—such as the return format (likely boolean), behavior when slug is found vs. not, or any location scope. It does not contradict annotations but also provides no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three words) but this is under-specification, not efficient succinctness. It front-loads nothing useful and provides no structure that aids an agent in understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, 3 params with minimal descriptions, and a vague one-line description, the tool is not adequately described. An agent cannot confidently know what this tool does, what it returns, or how to call it correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only locationId has a description), and the description itself adds no meaning to any parameter. It does not explain the purpose of postId (likely to exclude a post when checking uniqueness) or the required urlSlug beyond being the subject. The description utterly fails to compensate for the sparse schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Check url slug' is a near-tautology of the tool name 'blogs_check_url_slug_exists' and does not clarify whether 'check' means existence, availability, or format validation. It specifies a verb and resource but is too vague to distinguish from potential alternatives or to convey the actual intent (e.g., returns true/false if slug exists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, under what circumstances (e.g., before creating a blog post to verify uniqueness), or what alternatives exist. The description lacks any contextual cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond that—no mention of error behavior, return format, or edge cases. Since annotations cover the basic safety, a 2 reflects the minimal extra value provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (one sentence), but brevity is not conciseness here—it lacks substantive information. It is under-specified, providing no structure or key points. While short, it fails to earn its place because it conveys no useful content beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single param, no output schema), the description still needs to state what the business object contains or typical usage. It does neither. An agent cannot infer the return structure or any constraints, making it contextually incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter, businessId, with no description (schema description coverage 0%). The description does not explain what businessId is or any format expectations. With zero coverage and no compensation, the parameter semantics are entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Business' is essentially a restatement of the tool name, providing only a vague verb-resource combination. It does not specify what details are returned or how it differs from siblings like businesses_get_businesses_by_location. There is no scope or additional context, making it a near-tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers zero guidance on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or exclusions. An agent cannot determine when to prefer this over businesses_get_businesses_by_location or other get-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the annotations (destructiveHint=true, readOnlyHint=false), and the word 'Delete' is consistent with those flags. However, it adds no extra behavioral context—such as whether deletion is permanent, if it affects the event, or any side effects. Given annotations already convey destructive intent, the description could add value by explaining consequences but doesn't.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is under-specification rather than concise. It provides no structure or front-loaded context. Every word is minimal, but the tool needs more explanation to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a destructive operation, the description should specify what happens on success or failure, whether the notification must exist, and the impact of deletion. None of this is present. The tool is essentially a bare operation with no contractual details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the parameters (calendarId, notificationId) have no descriptions. The description should compensate but says nothing about what these IDs refer to or how they relate to the notification. An agent cannot infer parameter meaning from this description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Notification' is extremely vague and does not specify that it operates on calendar event notifications. It fails to distinguish from other delete tools like calendars_delete_calendar or calendars_delete_event. The tool name provides more clarity than the description, but the description itself is little more than a truncated version of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, what alternatives exist, or any conditions that should trigger its use. The description simply states the action without context. No mention of prerequisites, such as the notification needing to exist, or whether this deletes only event-specific notifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety aspects. However, the description adds no behavioral context beyond these, such as pagination, filtering, or response format. It neither contradicts nor enriches 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, but it is under-specified rather than efficiently concise. It provides no useful front-loaded information and reads as a minimal placeholder rather than a deliberate, informative summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no explanation of return values, filtering semantics, or how notifications are populated, the description is wholly inadequate. An agent cannot correctly select or invoke this tool based on this information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40% (skip and limit have descriptions, but deleted, isActive, and calendarId are undocumented). The description explains none of the parameters or their meanings. With coverage below 50%, the description needed to compensate but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get notifications' is vague and unspecific. It doesn't indicate these are event notifications nor distinguish this tool from similar siblings like calendars_find_event_notification or calendars_create_event_notification. It provides only a generic verb and noun with no resource context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description gives no context, prerequisites, or exclusions, leaving the agent without direction about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: false, idempotentHint: true, and destructiveHint: false, indicating a non-destructive but mutable operation. The description adds nothing about behavior beyond the word 'Update', so it provides minimal additional transparency. Not contradictory, but still inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short at two words, but this is under-specification rather than conciseness. It lacks essential content needed to understand the tool, so the brevity is not a positive attribute.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 18 parameters, 2 required, no output schema, and a two-word description, the tool is severely under-documented. An agent would have no idea what fields are critical, what the update affects, or how to invoke the tool correctly. The description is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 89%, so the input schema already documents the 18 parameters in detail. The description adds no parameter semantics beyond what the schema provides, but since coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update notification' is a tautology that restates the tool name without specifying what kind of notification, what it updates, or how it differs from siblings like calendars_create_event_notification or calendars_update_schedule. This gives an agent no actionable purpose information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It doesn't mention that it updates an existing event notification, nor any prerequisites or conditions under which it should be chosen over other calendar notification tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a mutating operation (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds no behavioral context beyond 'Create Note' — no effects, side effects, or constraints. Since annotations provide minimal safety signals and the description contributes nothing extra, this scores low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Create Note') but this is under-specification rather than effective conciseness. It lacks any structure or meaningful content, so it does not 'earn its place' — it merely echoes the tool name without adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no output schema, and minimal annotations, the description is grossly incomplete. It fails to indicate what the note contains, how it relates to the contact, or any operational details. An agent cannot reliably invoke this tool correctly based on this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only 'contactId' has a description). The description provides no explanation of parameters like 'body', 'title', 'color', 'pinned', or 'userId'. With such low schema coverage, the description must compensate but does not, leaving most parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Note' is essentially a restatement of the tool name, adding no specific verb-resource detail beyond what the name already conveys. It fails to specify that this creates a note on a contact, which is implied by the tool name and required parameter 'contactId'. This is close to a tautology, offering no differentiation from other create tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like contacts_create_task or contacts_update_note. No mention of prerequisites (e.g., contact must exist) or context for when this is appropriate. The description provides zero usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint) already convey that this is a safe, non-mutating read operation. The description adds no behavioral context beyond that—it doesn't explain what a 'duplicate' means, what the tool returns, or any edge cases. Since annotations carry the disclosure burden and the description adds nothing, it gets a low but not minimum score (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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is under-specified rather than concise. It lacks any structural elements like a purpose statement or usage hints. A single uninformative phrase does not earn credit for efficiency; it fails to convey necessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 optional parameters, no output schema, and a vague name. The description provides no information about what the tool returns, how it interprets 'duplicate', or when to call it. For a 3-parameter tool without an output schema, this description is completely inadequate 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: the 'email' and 'number' parameters explain URL-encoding, and 'locationId' mentions its default. The description adds nothing that enhances parameter understanding, so the baseline of 3 (schema does the heavy lifting) is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Duplicate Contact' is a tautology that merely restates the tool name. It fails to explain what a 'duplicate contact' is or what the tool actually does beyond the name. There is no verb-resource detail or distinction from other contact tools like contacts_get_contact or contacts_search_contacts_advanced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where a duplicate contact lookup is appropriate, nor does it reference any sibling tools for comparison. An agent given this description cannot infer the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description adds little. It does not mention whether removal is permanent, whether it applies to all tags on a contact or specific ones, or any side effects. It adds no behavioral context beyond the trivial phrase.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse, but this is under-specification rather than conciseness. It lacks any structure or front-loaded key information. While it is not verbose, it fails to earn its place by conveying actionable details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema and partial parameter coverage, the description is drastically incomplete. It provides no information about return values, error conditions, or the scope of the removal. An agent cannot predict the outcome of calling this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (contactId has a description, tags does not). The description 'Remove Tags' provides no additional meaning for either parameter, failing to clarify what the tags array contains or how contactId is used. It does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove Tags' repeats the tool name almost verbatim and fails to specify the resource (contact) or context. It does not distinguish from sibling tools like contacts_add_tags or locations_delete_tag, leaving the intended operation ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, conditions for removal, or relationships to other tagging operations. An agent gets no help selecting this tool over contacts_add_tags or locations_delete_tag.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond what annotations already provide (readOnlyHint=false, destructiveHint=false, idempotentHint=true). It does not disclose implications of updating (e.g., partial vs. full replacement), required fields, or side effects. While it does not contradict annotations, it also contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Update Task'), but this brevity is due to under-specification rather than deliberate conciseness. It fails to front-load any meaningful information and every word is essentially redundant with the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, low schema coverage, no output schema, and no behavioral or usage guidance, the description is grossly inadequate. An agent would be unable to correctly invoke this tool without external knowledge of the domain, making the description contextually incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 29% schema description coverage (taskId and contactId described), the description is entirely silent about the remaining parameters (body, title, dueDate, completed, assignedTo). It offers no hints about what fields are updatable, optionality, or typical usage, leaving the agent to guess from parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Task' is a tautology that restates the tool name 'contacts_update_task' without specifying the resource type, scope, or what 'update' encompasses. It does not distinguish from siblings like 'contacts_update_task_completed' or 'contacts_update_note', leaving the agent to infer the exact purpose from the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The agent receives no help in deciding between this and other contacts_* update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, confirming this is a write operation, but the description adds no behavioral context. It does not disclose potential side effects, such as whether existing data is overwritten, how duplicates are handled, or any permission requirements. Given annotations exist, the bar is lower, but the description still provides zero additional value beyond the bare verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, this is under-specification rather than conciseness. A single verb phrase lacks the structure needed to convey functionality. It is not an efficient summary of capabilities but an empty shell.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 24 parameters, nested objects, no output schema, and low schema coverage. The description is virtually nonexistent, offering no guidance on required vs optional fields, date formats, duplicate handling, or return values. It is completely inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 21%, so the description must compensate for the many undocumented parameters. However, the description contains no parameter-related information whatsoever. With 24 parameters and many having no schema description, the absence of any explanation leaves agents unable to understand what fields to supply or how they relate to the upsert behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert Contact' is a direct restatement of the tool name with no additional detail. It does not explain what 'upsert' means, whether it creates, updates, or both, nor does it differentiate from sibling tools like contacts_create_contact or contacts_update_contact. The verb and resource are present, but the description is tautological and fails to provide any meaningful purpose clarification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives. The description does not mention scenarios where an upsert is preferred over a create or update, nor does it reference any prerequisites or exclusions. An agent cannot infer appropriate usage from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond that, such as whether the result is paginated, what the response looks like, or any side effects. The description is silent where it could add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It adds no useful information and does not earn its place. A one-word description would be equally informative, so it fails to leverage brevity effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and a sibling that returns submissions, the description is completely inadequate. It does not mention what the tool returns, how pagination works, what 'type' refers to, or how it relates to forms_get_forms_submissions. An agent cannot correctly call this tool without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about parameters. The input schema covers only 50% of parameters (limit and locationId have descriptions; skip and type do not). With such low schema coverage, the description should compensate by explaining the parameters, but it does not. Agents are left without guidance on how to use skip or type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Forms' is essentially a tautology of the tool name forms_get_forms. It names a generic verb and resource but provides no specifics about what forms are returned, how they are filtered, or how this differs from the sibling forms_get_forms_submissions. It does not distinguish itself clearly from the other forms tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus forms_get_forms_submissions or any other sibling. There is no mention of prerequisites, typical use cases, or exclusions. An agent would have to infer entirely from the name.
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?
Annotations already provide destructiveHint=true and idempotentHint=true, so the description does not need to repeat that. However, it adds no additional behavioral context such as permanence, cascading effects, or authentication requirements. Since the description carries no behavioral disclosure beyond what annotations already state, it fails to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words, which is not concise but under-specified. It lacks any informative content and does not earn its place; it could be entirely removed without loss, as the tool name and schema already convey the core action. Extremely low information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with three parameters and no output schema, the description should explain the effect (e.g., permanently removes the template) and any constraints (e.g., cannot delete if used in invoices). It provides none of this, making it incomplete for an agent to correctly judge consequences or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds nothing about parameters, but since the schema already documents each field (templateId, altId, altType) and their purpose, the base score is appropriate. No extra semantic value is contributed by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete template' is a generic restatement of the tool name, which already specifies 'invoices_delete_invoice_template'. It does not clarify that this deletes an invoice template specifically, nor does it distinguish it from sibling tools like invoices_delete_invoice or invoices_delete_estimate_template. It is a tautology rather than an explanation of the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as whether the template must not be in use, nor any conditions that would make a different delete tool more appropriate. The description is completely silent on usage context.
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?
Annotations indicate readOnlyHint=false, but the description adds no behavioral context. It fails to disclose that action selects the delivery channel (email, SMS, or manual), that sending may trigger notifications, or any permission requirements. It carries no 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.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is under-specified rather than concise. It omits essential context and provides no front-loaded useful information, making it far too uninformative for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, 4 required, and no output schema, the description is wholly inadequate. It does not explain what the action parameter controls, what happens on send, or what response to expect. An agent would lack critical information to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes all parameters with 88% coverage, so the description does not need to redundantly explain them. However, it also adds no extra meaning about nuances like the 'action' enum or 'sentFrom' conditions. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send Estimate' names a verb and resource but is essentially a restatement of the tool name. It does not specify the sending channels (email/SMS) or differentiate from similar tools like invoices_send_invoice, leaving the agent without enough information to pick it correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention conditions, exclusions, or related tools (e.g., invoices_send_invoice for invoices), so an agent cannot determine when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the description should clarify the side effects. 'Create & Send' implies mutation, but it doesn't state what happens to existing invoices (it can update via 'id'), whether it sends immediately, or what the response contains. No behavioral detail beyond the minimal verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a two-word fragment, which is not conciseness but under-specification. It lacks essential structure and fails to front-load any useful information. There is no attempt to convey purpose, scope, or context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 27 parameters, 9 required, and nested objects, the description must provide context on required fields, examples, or behavior. It provides none. The output schema is absent, so the description is the only source of outcome details, and it's missing entirely. Completely inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (85%), so the parameters are largely documented in the schema itself. The description adds no parameter semantics, but per the baseline rule for high coverage, a score of 3 is appropriate. It doesn't compensate for any gaps, but it's not required to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create & Send' is vague and does not specify the resource (invoice is implied by the name, but the description alone lacks it). It doesn't distinguish from siblings like invoices_create_invoice or invoices_send_invoice, and the schema's optional 'id' suggests it can also update, which is not mentioned. The purpose is unclear and under-specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. There are many invoice-related siblings (create, send, update), but the description gives no indication of when this combined create-and-send tool is appropriate or when to prefer a separate create/send. Completely lacking usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) provide basic behavioral info, the description adds nothing beyond them. It doesn't disclose return format, pagination, or any edge cases. Since the description adds no extra behavioral context, it falls short even with annotations lowering the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise but at the cost of substance. It lacks any explanatory content, making it under-specified rather than efficiently concise. There is no structure beyond a single phrase, and it doesn't front-load any useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 optional parameters and no output schema, the description is completely inadequate. It doesn't explain what the tool returns, how parameters interact, or any practical usage context. An agent cannot correctly call this tool based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover all 7 parameters (100% coverage), so the baseline is 3 even without parameter info in the description. The description adds no parameter semantics, but since the schema is comprehensive, it doesn't need to compensate. This score reflects the schema's sufficiency rather than the description's contribution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is 'Get lost reason', which essentially restates the tool name without adding any context. It doesn't specify that this relates to opportunities, what a lost reason is, or how it differs from other opportunity-related tools. It is a tautology with no informative content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no mention of prerequisites or scenarios where it applies. An agent has zero information on when to invoke it, making it impossible to select appropriately based on the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which cover the safety profile. The description adds no behavioral context beyond the word 'Update' and does not disclose any side effects, authorization requirements, or limitations. It neither contradicts the annotations nor enriches them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. Every word is trivial and adds no value. There is no structure or front-loading of important information; it is simply a restatement of the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with eight parameters and no output schema, the description is wholly inadequate. It provides no information about what an update entails, what fields are updatable, any constraints, or expected results. An agent would have to rely solely on the input schema and annotations, which are insufficient to guarantee correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38%, and the description provides no additional meaning for the parameters. Fields such as name, status, assignedTo, monetaryValue, and pipelineStageId lack explanations in both the schema and the description. The agent is left with no information about what these parameters represent or how they interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Opportunity' identifies the verb and resource, but it is essentially a tautology of the tool name, providing no additional specificity. It does not mention which fields or aspects of an opportunity can be updated, nor does it distinguish this from sibling tools like opportunities_update_opportunity_status, which is a more focused 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context is provided about prerequisites, typical use cases, or exclusions. The description offers no help to an agent deciding between this and opportunities_update_opportunity_status or other related utilities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no additional behavioral context such as what is returned, pagination behavior, or any special constraints. It does not contradict annotations, but it also contributes nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('List Products'), which is under-specification rather than efficient conciseness. It omits necessary context and does not structure information in a useful way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, no output schema, and a description that is just 'List Products', the tool is severely under-documented. An agent cannot determine what the tool returns, how pagination works, or what 'invoices' has to do with products. This is completely inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with detailed descriptions for all 12 parameters (limit, expand, offset, etc.), so the schema handles parameter semantics well. The description itself adds nothing about parameters, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Products' directly contradicts the tool name 'products_list_invoices', which suggests it lists invoices related to products. The verb and resource are vague and misleading – it could be either products or invoices. It fails to distinguish from siblings like products_list_prices_for_product or invoices_list_invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is absolutely no guidance on when to use this tool versus alternatives. No mention of typical scenarios, exclusions, or related tools. The agent is left to infer usage from an ambiguous one-liner.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. However, the description adds no additional behavioral context such as pagination, filtering behavior, response format, or any limitations. It provides zero extra 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short phrase that is under-specified rather than concisely informative. It lacks structure and does not front-load any useful details. It is not a well-formed sentence that earns its place; it's a placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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 is completely inadequate. It does not state what the list contains, how filtering works, or the relationship to templates. An agent has no idea what this tool returns or how to use it correctly, making it insufficient for any meaningful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has descriptions for all 8 parameters, achieving 100% schema coverage. The description does not add any meaning beyond the schema, which is acceptable given the baseline of 3 for high coverage. However, it could have provided context like the default location or how status works, but it doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List documents' is extremely vague and does not specify what kind of documents, the context (proposals, contracts), or how it differs from the sibling proposals_list_documents_contracts_templates. It essentially restates the action from the name without adding resource type or scope, providing no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The sibling proposals_list_documents_contracts_templates exists but is never mentioned, and no conditions or scenarios are provided to help an agent choose between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description 'Delete CSV' aligns with that without contradicting it. However, the description adds no extra behavioral context such as permanence, side effects, or any preconditions. With annotations present, the description's minimal wording is insufficient to convey the implications of the deletion, scoring low but not failing due to consistency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words) and lacks any structure or elaboration. While conciseness is valued, this is under-specification rather than efficient brevity. Important context is omitted, making the description feel incomplete rather than intentionally lean. The front-loading principle is not violated, but the content is so sparse it fails to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a delete operation with two parameters and no output schema, but the description provides no explanation of what 'CSV' refers to in this social media posting context, what the 'id' identifies, or any consequences of the action. An agent would be left guessing about the purpose and implications, making the description wholly inadequate for safe or correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'id' and 'locationId' have descriptions in the schema. Per the rubric, high coverage sets a baseline of 3, and the description adds no additional parameter meaning. Thus a score of 3 is appropriate—it does not harm, but contributes nothing beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete CSV' is essentially a tautology of the tool name 'social_media_posting_delete_csv'. It states the verb and resource but does not clarify what the CSV represents in the context of social media posting, making it indistinguishable from merely reading the name. For an agent to understand what this tool is for, it needs to know that this deletes a CSV file used for bulk posting, but the description offers no such context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The sibling list includes tools like social_media_posting_delete_csv_post and social_media_posting_delete_post, but no mention is made of when to delete a CSV versus those other deletion tools. No prerequisites, conditions, or workflow steps are described, leaving the agent entirely without direction on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. However, the description adds no behavioral context beyond these annotations. It does not explain what kind of status information is returned, whether it requires a specific authentication scope, or how it behaves with pagination parameters. Since the description carries no extra disclosure, it adds little value even with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, this is not conciseness but under-specification. A single phrase without any additional sentences fails to structure necessary information such as what the status refers to, what the response looks like, or how to interpret parameters. The brevity is not earned; it simply omits essential content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the abundance of similar social media posting tools and the lack of an output schema, the description is completely inadequate. It does not explain what 'upload status' means in the context of the API, how the upload is identified (e.g., by post ID, by batch), or what fields are returned. An agent would have no idea how to correctly construct a call or interpret the result. This tool clearly requires far more context to be usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40% (userId and locationId have descriptions, while skip, limit, and includeUsers do not). The tool description 'Get Upload Status' does not compensate for this gap at all—it provides no additional explanation of any parameter's purpose, format, or relationship to upload status. For a tool with five parameters, this is a critical omission that leaves the agent guessing about skip/limit semantics and the role of includeUsers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Upload Status' simply restates the action already implied by the tool name without adding any specificity about what 'upload status' refers to (e.g., which posts, which platform, whether it's a batch or individual upload). It does not distinguish this tool from the many other social_media_posting_* tools that also involve retrieving information, such as get_post or get_posts. The verb and object are present but so generic that an agent cannot infer the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With numerous sibling tools like social_media_posting_get_post, social_media_posting_get_posts, and social_media_posting_get_account, there is no mention of the scenario where checking 'upload status' is appropriate. No conditions, prerequisites, or exclusions are given, leaving the agent without any decision support.
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?
Annotations indicate readOnlyHint=false, confirming a write operation, but the description adds no behavioral context beyond that. It does not disclose side effects, required permissions, integration dependencies, or any other operational details. With no additional context, the description provides no value beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise but at the cost of substance. It is a single sentence that merely restates the tool name, offering no useful information to the agent. While it is brief, it is not effectively structured to front-load any actionable details, making it under-specified rather than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with four parameters and no output schema, the description is grossly insufficient. It does not explain what a conversation form is, how it fits into the ad manager workflow, or what the expected outcome is. The lack of any contextual detail makes it impossible for an agent to determine when and how to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters have their own descriptions. The tool description adds no parameter information, but per the rubric the baseline is 3 when the schema is thorough. The description does not enhance understanding of parameters like 'questions' or 'locationId' beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create conversation form' is a near-tautology of the tool name, restating the verb and resource without adding clarity. It does not differentiate this tool from the closely related sibling ad_manager_fb_create_page_lead_form, which also creates a form. The description fails to specify the unique purpose or scope of a conversation form.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or scenarios where a conversation form is appropriate compared to page lead forms or other ad manager creation tools. An agent receives zero directional information.
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?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, implying a state-changing operation. The description adds no additional behavioral context, such as what the resume process entails, potential side effects, or requirements. It simply restates the action without elaborating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (three words), which qualifies as concise but is severely under-specified. It lacks structure and fails to convey essential information. This is not effective conciseness but rather a minimal placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two parameters, a required one, and no output schema, the description is wholly inadequate. It doesn't explain what happens when resuming an ad set, any dependencies, or expected outcomes. An agent has no context to correctly execute this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: only locationId has a description, while adsetId is left undocumented. The description does nothing to clarify adsetId's format or purpose, and it doesn't compensate for the incomplete schema. Thus, the description provides no parameter-level value beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Resume ad set' clearly identifies the action and resource, but it adds no value beyond the tool name itself. It doesn't differentiate from siblings like ad_manager_fb_resume_ad or ad_manager_fb_resume_campaign, so an agent could easily pick the wrong one without further context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling resume tools. No mention of prerequisites (e.g., ad set must be paused) or conditions like integration state. An agent receives no context about the appropriate scenario.
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?
Annotations provide only generic flags (e.g., openWorldHint=true, destructiveHint=false) with no explanatory context. The description itself discloses no behavioral traits—no side effects, no permission requirements, no reversibility, no return semantics. For a mutation tool with such minimal annotation text, the description carries the full burden and fails to meet it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it is essentially a title restatement. This is under-specification rather than conciseness—there is no front-loaded critical information to help the agent decide or act.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and nontrivial domain context (ad management on LinkedIn), the description provides almost nothing. An agent cannot infer what publishing does, what state it changes, or what a successful call looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions ('Ad identifier', 'Location identifier Defaults to GHL_LOCATION_ID'), so the baseline is 3. The description adds no parameter-level insight beyond what the schema already provides, which is acceptable given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Publish ad campaign group' restates the tool name with no additional specificity. It provides a verb and resource but no detail on what publishing entails, who it's for, or what distinguishes it from sibling tools like ad_manager_li_upsert_campaign_group or ad_manager_li_update_ad_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description makes no mention of prerequisites, conditions, or exclusions, leaving the agent to guess when publishing a campaign group is appropriate.
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?
Annotations declare readOnlyHint=true and idempotentHint=true, which the description does not contradict. However, the description adds no behavioral context beyond that—no mention of return format, scope, or limitations. For a tool with no output schema, this is a significant gap, and the description fails to disclose anything useful about its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise in length but severely under-specified. It reads as a placeholder rather than a deliberate summary. There is no front-loading of key information, and it fails to convey the tool's purpose or usage, so it is not appropriately sized for the agent's needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters (1 required), no output schema, and no description of return values or expected behavior, the description is far from complete. An agent would have no idea what this tool does or how to call it effectively—only that it relates to search targeting in some unspecified way.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—each parameter has a terse description (e.g., 'Query parameter', 'Targeting facet'). The tool description itself adds no extra meaning. Per the baseline for high schema coverage, a score of 3 is appropriate, but the description could have explained how parameters interact or provided examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search targeting options' is a vague noun phrase. It does not state a clear action (e.g., 'search for targeting options') or the resource it operates on (LinkedIn ads). It provides no differentiation from sibling tools like ad_manager_fb_search_targeting or ad_manager_google_search_targeting, leaving the agent unable to distinguish this tool from its peers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of platform-specific context, prerequisites, or typical use cases. The agent is left to guess based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic flags (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), but the description adds no behavioral details such as side effects (e.g., sending messages, creating sessions) or expected execution semantics. The only extra info is 'Deprecated', which is a status hint rather than behavioral disclosure. No contradiction with annotations, but the description fails to supplement them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—just three words—but this is under-specification rather than concise efficiency. It front-loads nothing useful and omits all operational detail. Every word is 'earned' in the sense that there are no extras, but the lack of substance makes it ineffective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex execution tool with 9 parameters, nested objects, and no output schema, yet the description offers no guidance on how to use it correctly. It fails to explain return behavior, how to sustain conversation context using executionId, what inputVariables should contain, or why one would choose this deprecated tool over its replacement. The description is wholly inadequate for an agent to invoke it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 78%, which is moderate, and the schema includes useful descriptions for key parameters like executionId, contactId, and versionId. However, the description itself adds zero parameter context, and does not help clarify any fields that lack schema descriptions (e.g., 'source' and 'attachments' are partially undocumented). With only 78% coverage, the description should compensate for the gaps but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Execute Agent (Deprecated)' merely restates the tool name and adds no specific details about what executing an agent involves. It does not differentiate this deprecated tool from its non-deprecated sibling 'agent_studio_execute_agent', and 'Deprecated' alone provides no functional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description does not mention that a preferred non-deprecated version exists (agent_studio_execute_agent) or any conditions that should lead an agent to choose this tool. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false. The description 'Promote to Production' aligns with a state-changing action but adds no extra details about side effects, authentication, or what happens if the version is already in production. It provides no 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely brief, this is under-specification rather than conciseness. There is no structure, no front-loading of critical information, and every word is generic. It does not earn its place because it carries almost no informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a promotion/publish action with 6 parameters, one required, and no output schema, this description is completely inadequate. An agent cannot determine what the tool does beyond a vague 'promote to production', what parameters to provide, or what the outcome/expectations are. The description is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (below 80%), so the description must compensate. It does not mention any parameters or their meaning. The required versionId has no schema description and the tool description offers no hints. This fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Promote to Production' states a verb and a target, but it is vague about what is being promoted. It does not mention agents or versions, which the tool name implies. It is nearly a paraphrase of the tool name and does not distinguish this from other publish/promote tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites, no mention of required inputs like versionId, and no context about the promotion workflow. The description provides zero usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond the annotations. Annotations indicate a non-read-only, possibly world-modifying operation, but the description does not explain what 'update' entails (e.g., whether it replaces the entire version or patches fields, whether it is reversible, or how it interacts with publish/promote flows). This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse, which is under-specification rather than appropriate conciseness. It lacks any context that would help the agent use the tool correctly for a complex 13-parameter operation. The two-word description does not convey the necessary structure or affordances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, nested objects, no output schema), this description is wholly inadequate. It provides no context about the update semantics, required versus optional fields, or behavior, leaving the agent unprepared to invoke the tool correctly. The low word count does not compensate for the tool's sophistication.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high at 85%, so the baseline is 3 even with no parameter details in the description. The description does not enhance parameter understanding, but the schema already documents most parameters, including edges/nodes and other fields, so the agent has baseline information from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Agent' provides only a basic action and object, but fails to indicate that this tool updates a specific version of an agent, not the agent itself. It does not differentiate from siblings like agent_studio_update_agent_metadata or agent_studio_create_agent, leaving the agent without a clear understanding of the tool's specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. With multiple agent-related update tools in the sibling list, the description gives no context about scenarios, prerequisites, or exclusions, leaving the agent to infer the tool's purpose without support.
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?
The description adds no behavioral information beyond what annotations already convey (readOnlyHint=false implies a write operation). It does not disclose side effects, required permissions, or the outcome of the operation, and the openWorldHint annotation is left unexplained. With annotations present, the bar is lower, but the description still contributes nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is under-specified rather than concise. A single phrase that restates the title provides no value and fails to front-load any useful information. The brevity is not an asset; it is a deficiency given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters and no output schema, the description should explain what a block slot is, how start/end times are formatted, and what the response looks like. None of this is present. The description is completely inadequate for an agent to call the tool correctly and understand its effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all six parameters, including the mutual exclusivity of calendarId and assignedUserId. Since schema description coverage is 100%, the baseline is 3 even though the description itself adds no parameter context. The schema independently documents the parameters sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Block Slot' essentially restates the tool name with no additional context. It does not explain what a block slot is in the calendar context, nor does it differentiate this from other calendar creation tools like calendars_create_appointment or calendars_create_calendar. An agent cannot determine the specific purpose based on this text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of conditions, prerequisites, or exclusions. The description gives no indication of the scenarios where creating a block slot would be appropriate.
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?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. However, the description adds no behavioral context beyond these flags—no mention of irreversibility, cascade effects, or any side effects. It fails to add value beyond what structured fields already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but this is under-specification rather than effective conciseness. It lacks any structure or substantive information, making it unhelpful for an agent. It is not 'front-loaded' with key details because there are no details at all.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with a nested object parameter and no output schema, the description is severely incomplete. It omits any information about return values, error conditions, or special cases like recurring events. The tool's complexity demands more context than a single phrase.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema descriptions are thorough, covering both body and eventId with a useful note on recurring events. Since schema coverage is 100%, the description does not need to add parameter details, and its silence here is acceptable. It meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Event' is a direct restatement of the tool name, providing no additional context or differentiation from similar calendar delete tools like calendars_delete_schedule or calendars_delete_calendar. It is a tautology that does not help an agent understand the specific resource being acted upon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers zero guidance on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or distinguishing factors from other delete operations, leaving the agent to guess based solely on the name.
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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds zero behavioral context beyond the name. It does not describe what is returned, any side effects, or special behaviors (e.g., handling of recurring events). The description does not contradict annotations, but it adds no value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is under-specification rather than conciseness. It lacks any useful information that would help an agent understand the tool's purpose or usage. Every sentence should earn its place, but here there is no sentence, just a vague phrase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter and no output schema, the description is completely inadequate. It fails to explain what an appointment is, what the return value looks like, or any edge cases such as recurring appointments. The annotations provide some safety context, but the description itself leaves the agent without essential information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for eventId is detailed and covers 100% of parameters, explaining that for recurring appointments the masterEventId should be sent to modify the original series. The tool description contributes nothing beyond the schema, so a baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Appointment' is essentially a tautology of the tool name. It does not specify what kind of appointment, what resource it operates on, or distinguish it from other calendar tools like calendars_get_calendar_events or calendars_get_slots. It provides minimal verb+resource but no specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like calendars_get_calendar_events or calendars_get_slots. No context is provided about scenarios, prerequisites, or why one would choose this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations correctly indicate readOnlyHint, idempotentHint, and destructiveHint false, which the description does not contradict. However, the description adds no behavioral context beyond the name—no mention of what data is returned, whether it requires authentication, or what happens when locationId is omitted. Since annotations already cover the safety profile, the description should add value but fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The text is extremely short, but this is under-specification rather than effective conciseness. It does not front-load any useful information or structure the content beyond the bare phrase 'Get Groups.' It fails to convey the tool's function or any relevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool has only one optional parameter and no output schema, the description is still incomplete. It does not clarify what 'groups' refers to, what the API returns, or how the response is structured. An agent would have no idea what to expect from this endpoint, making it insufficiently documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines the locationId parameter with a clear description and default behavior (defaults to GHL_LOCATION_ID). With 100% schema coverage, the baseline is 3. The tool description adds nothing about parameters, but the schema already provides sufficient semantics for this single optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Groups' is a tautology that restates the tool name. It fails to specify what kind of groups are being retrieved (calendar groups, user groups, etc.) and does not differentiate it from sibling tools like calendars_get_calendars or calendars_create_calendar_group. An agent cannot determine the tool's actual purpose from this text alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention any context, prerequisites, or exclusions. The description provides zero information about suitable use cases or how it differs from other calendar-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) already communicate that this is a read-only, non-destructive operation. The description adds no further behavioral context, such as pagination details (skip/limit), filtering via query, or the return format. Since annotations are present but the description contributes nothing beyond them, a score of 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, so it is concise. However, structure and front-loading are weak because it merely repeats the name with no useful information first. It is appropriately short but not effectively structured to convey meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 1 required, and no output schema, the description is completely inadequate. It fails to mention that contacts are returned as a list, how pagination via skip/limit works, what the query parameter does, or the default behavior for locationId. An agent cannot correctly call this tool based on this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only locationId has a description). The tool description does not explain any parameters—skip, limit, query, businessId, or locationId—nor does it clarify their purpose or format. With such low schema coverage, the description must compensate but entirely fails to do so, leaving all 5 parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Contacts By BusinessId' is essentially a restatement of the tool name with no additional explanation of what the tool actually does, such as whether it returns a list of contacts, what fields are included, or how it differs from sibling tools like contacts_get_contacts. It lacks specificity about the resource and scope, making it barely more informative than the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like contacts_get_contacts, contacts_search_contacts_advanced, or contacts_get_contact. The description does not mention context, prerequisites, or exclusions, leaving the agent without any direction for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond the name. Annotations already indicate destructiveHint=true and idempotentHint=true, but the description provides no additional context such as whether the removal is permanent, if it affects related data, or if special permissions are required. With annotations carrying the safety profile, the description offers little extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words, which is concise but under-specified. It lacks any structure that would convey useful information, such as a complete sentence explaining the action's scope or effects. This is not a case of well-crafted conciseness but rather an absence of necessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no output schema, the description should at least hint at what happens after removal, side effects, or return behavior. It provides none of this. The tool's simplicity doesn't excuse the lack of context; an agent would not know what to expect or how to verify success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% – contactId is described in the schema, but 'followers' (an array of strings) has no schema description. The description itself provides zero parameter semantics, so the tool adds no clarity about what the 'followers' array should contain (e.g., contact IDs, user IDs, other identifiers) or any constraints. This leaves a significant gap that the description fails to fill.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove Followers' is a verb-noun phrase but lacks the target resource context. It doesn't specify that the followers are being removed from a contact, which is only clear from the tool name. It also doesn't distinguish from similar operations like removing followers from opportunities or from adding followers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool or how it relates to alternatives. A sibling tool 'contacts_add_followers_contact' exists for adding followers, but the description gives no mention of this or any criteria for choosing one over the other. No context on prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, indicating a write operation, but the description provides no additional behavioral context. It does not state what side effects occur (e.g., creating a new conversation thread), whether any notification is sent, or what the outcome is. The description adds zero value beyond the annotations, failing to explain the operation's effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Create Conversation'), which is under-specification rather than genuine conciseness. It lacks any structural elements like context, examples, or preconditions. Every word is present, but the description is so minimal that it fails to inform the agent, similar to the calibration example of a single verb phrase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema, the description does not explain what a conversation is, how it relates to contacts or locations, what the response will look like, or any state changes. Even basic context like 'creates a new conversation associated with the given contact' is missing. The description is wholly inadequate for an agent to understand the tool's role and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (contactId and locationId) with clear descriptions, including the default for locationId. The tool description itself adds no parameter information, but since the schema already documents them adequately, a baseline score of 3 is appropriate. No additional semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Conversation' states a verb and resource, but it is essentially a restatement of the tool name and adds no specification of what a conversation is in this system or how it differs from related operations. It does not distinguish from sibling tools such as conversations_add_an_inbound_message or conversations_search_conversation, so it fails to convey the unique purpose beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description offers no context about prerequisites (e.g., contact must exist), common use cases, or why one would choose this over conversations_update_conversation or conversations_send_a_new_message. With many sibling conversation tools, the lack of any usage direction is a critical gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. However, the description adds no behavioral detail beyond the annotations—e.g., it doesn't state that it retrieves the full email content, whether it requires any special permissions, or what happens if the ID is invalid. Since annotations cover the safe-read aspect but the description contributes nothing extra, it falls short of the bar for a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but conciseness should not sacrifice essential information. It is under-specified and lacks any structure that would help an agent understand the tool's behavior. It reads as a fragment rather than a clear, informative sentence. Every word counts, but here there are too few words to convey meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only one parameter and no output schema, the description should at least clarify the purpose and what is returned. It does neither. An agent cannot determine what 'email' refers to, how it relates to conversations, or what the response will look like. The annotations cover safety but not the semantic details. This is a severe gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the sole parameter 'id' as 'Path parameter id.' which is minimally informative. The tool description provides no additional guidance on the parameter's format, meaning, or usage. Even though schema coverage is 100%, the description's failure to add any context about the ID (e.g., what type of ID, where to find it) leaves the agent with no extra value. A baseline of 3 is not earned because the description doesn't supplement the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get email by Id' is a near-verbatim restatement of the tool name, adding no contextual detail. It names a resource (email) and an action (get), but fails to specify what kind of email, what the result includes, or how it relates to conversations. It does not distinguish from siblings like conversations_get_message or conversations_get_messages, so an agent would not know if this returns a specific email within a conversation or something else.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives. No mention of scenarios, prerequisites, or exclusions. With many 'get' tools in the sibling list, the agent is left to guess which one is appropriate. This is a complete lack of usage context.
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?
Beyond the annotations (readOnlyHint false, idempotentHint true, etc.), the description discloses no behavioral traits. It doesn't mention side effects, idempotency implications, or any constraints on the update operation. Since annotations already cover the safety profile, the description adds zero value here, failing to provide any context beyond what's already structured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short at 24 characters, but this is under-specification rather than conciseness. It provides no structure or prioritization of information, and the single phrase offers no substance for the agent to parse. It fails to be appropriately sized because it omits critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and no output schema, this tool requires more contextual detail to be called correctly. The description is grossly incomplete, lacking any explanation of the update effect, field relationships, or constraints. An agent would have no understanding of how to perform the update correctly or what the outcome would be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description adds no parameter semantics; it doesn't explain relationships between fields (e.g., that resubscription_legal_form_id is only relevant when archiving) or any conditional logic. Since schema fully documents each parameter, the description doesn't need to compensate, but it also doesn't enrich the schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is exactly 'Update Custom Subtype', which restates the tool name without any additional detail. It doesn't specify which fields are updatable or distinguish this from siblings like conversations_create_custom_subtype or conversations_update_conversation. This is essentially a tautology, providing minimal clarification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool, when not to, or any alternatives. It is silent on usage context, prerequisites, or exclusions, leaving the agent with no direction on appropriate invocation scenarios.
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?
Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, but the description adds no behavioral details. It does not mention side effects, permissions, reversibility, or interaction with locationId defaults. The description contributes nothing beyond the annotations, which themselves are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—a single sentence. While it is front-loaded, it does not earn its place because it simply repeats the tool name. Conciseness is appropriate, but the content is under-specified, offering no additional value beyond the identifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with three parameters and no output schema, this description is incomplete. It doesn't explain what the folder is used for, what the response looks like, or how it relates to custom fields. The agent receives no guidance on expected results or prerequisites, making the tool hard to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters, so schema_description_coverage is 100%. Per the rubric, the baseline for parameter semantics is 3 when the schema fully documents parameters. The description adds no further explanation, but the schema already covers meaning adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Custom Field Folder' merely restates the tool name in sentence form. It provides a verb and resource but adds no context about what a custom field folder is, how it differs from a custom field, or its purpose within the system. Without sibling differentiation, it barely clarifies which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, when not to, or what alternatives exist. The description gives no context about scenarios where creating a folder is appropriate versus other custom field operations. This leaves the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Create template', which implies a write operation consistent with readOnlyHint=false. However, it discloses no behavioral details such as whether this overwrites existing templates, what the response contains, or any side effects. The annotations provide basic safety info but the description adds nothing beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single two-word phrase, which is under-specified rather than concise. It lacks any structure or front-loading of key information. While brevity is generally good, this is so minimal it provides no value beyond the tool name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, many nested objects, no output schema), this description is grossly inadequate. It does not mention required fields, what the template is used for, or any usage examples. An agent cannot confidently call this tool correctly without extensive external reference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides zero parameter information. The schema covers 65% of parameters with descriptions, leaving several (e.g., currency, internal, termsNotes) undocumented. The description does not compensate for these gaps, forcing the agent to inspect the schema directly and puzzle over undefined fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create template' is extremely generic and fails to specify that this creates an invoice template specifically. It doesn't distinguish from sibling tools like invoices_create_estimate_template or invoices_create_invoice. The name provides some context, but the description adds no specificity beyond a bare verb and noun.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus other invoice-related creation tools. No mention of prerequisites, common use cases, or alternatives. An agent receives no help in deciding between creating an invoice, an estimate, or a template of either type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. However, the description adds no behavioral context beyond these annotations; it does not explain that generating a number is side-effect-free or how it behaves. It does not contradict the annotations, so this is not a contradiction, but it adds no value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise, but it lacks any structure or additional information. It is under-specification rather than effective conciseness; it does not help the agent understand the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has optional parameters, no output schema, and annotations cover safety, but the description is still inadequate. It does not explain the purpose, when to call it, or what the returned invoice number represents. Even for a simple tool, the description should provide some context beyond the name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—both altId and altType have clear descriptions in the schema. The description adds nothing about parameters, but the schema fully documents them, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Generate Invoice Number' is a tautology—it merely restates the tool name without providing any additional meaning. It does not specify what the operation does, what resources are involved, or how it differs from siblings like invoices_generate_estimate_number.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of contexts, exclusions, or prerequisites. An agent would have to infer usage solely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral context beyond the HTTP method—no mention of pagination behavior, response format, or the fact that the 'type' parameter filters results. The description's 'email/sms' wording also ignores the 'whatsapp' enum value, which is a minor inconsistency but not a contradiction of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single fragment ('GET all or email/sms templates') that is extremely short but also under-specified. It lacks any structure to guide the agent—no front-loaded purpose, no mention of key parameters, and no sentence break. This is closer to a tautology than an informative description, though it does include a verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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, and low schema coverage, this description is wholly inadequate. It doesn't explain what the tool returns, how pagination works, how to use the 'type' filter, or what 'deleted' does. An agent cannot correctly invoke this tool based on this description alone, especially given the sibling tools with clearer semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only originId and locationId have descriptions). The description's phrase 'all or email/sms' hints that the 'type' parameter can filter results, but it doesn't name the parameter or explain the meaning of 'all' (likely omitting type). It provides no value for skip, limit, or deleted parameters, so it fails to compensate for the poor schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('GET') and a resource ('templates'), but the scope is ambiguous: 'all or email/sms' omits the 'whatsapp' type that exists in the schema, and it fails to mention the 'location' context implied by the tool name. It does not clearly differentiate from sibling tools like emails_fetch_template or locations_get_location_tags, leaving the agent to guess what this tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives. No mention of filters, pagination parameters (skip/limit), or the deleted flag. The description does not explain that this is for fetching messaging templates for a location, nor when someone would prefer this over emails_fetch_template or other template-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. However, the description adds zero behavioral context beyond the annotations—nothing about what the response contains, potential errors, or the meaning of 'custom value'. Since it does not contradict annotations but also provides no added transparency, this low score reflects the lack of contribution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is due to under-specification rather than conciseness. It omits essential information about the tool's purpose and context, making it insufficient for an agent to understand its role. A good concise description should still be informative; this one is merely truncated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-id tool, the annotations and schema cover safety and parameter format, but the description fails to explain what a custom value is or how this tool fits into the broader locations API family. With no output schema and a vague description, the agent lacks enough context to confidently invoke this tool correctly, especially given the existence of related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters ('id' and 'locationId' are described). The description does not add any extra meaning beyond what the schema already states, so the baseline score of 3 applies; no additional semantics are provided or needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Custom Value' is a tautology that restates the tool name without clarifying what a custom value is in this context. It does not distinguish from the sibling tool locations_get_custom_values (plural) or any other related tools, leaving the agent to infer that this fetches a 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The plural variant locations_get_custom_values exists, and there are create/update/delete siblings, but the description offers no context about retrieval by ID or the optional locationId parameter. The agent is left without direction on selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context, such as pagination behavior, response structure, or any filtering details. Since it adds no value beyond annotations, it earns a low but not contradictory score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words, but this is under-specification rather than effective conciseness. It lacks the substance needed to make those words valuable. Every sentence should earn its place; this one earns nothing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain what the response contains or any relevant aspects like pagination. None are mentioned. The tool is a list operation with a required orderId; at minimum it should clarify what 'fulfillment' refers to and that the result is a list. This is inadequate for a useful tool definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (altId, altType, orderId all have descriptions). The description adds no extra meaning to the parameters, but the baseline is 3 when the schema is fully descriptive. No gaps to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List fulfillment' is a near-verbatim restatement of the tool name (payments_list_order_fulfillment). It fails to specify what a fulfillment is, what the returned list contains, or how it differs from other payment listing tools like payments_list_orders or payments_list_subscriptions. This is a tautology rather than a clarifying statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides zero guidance on when to use this tool versus alternatives, such as payments_list_orders or the sibling payments_create_order_fulfillment. It does not mention the required orderId or any prerequisites, so an agent has no basis to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=false, destructiveHint=false, and idempotentHint=true, the description adds zero additional behavioral context. It does not mention side effects, field overwrite behavior, or any requirements. The description is entirely silent on behavioral traits beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that repeats the tool name, which is under-specification rather than effective conciseness. It lacks structure and fails to provide any useful information, making it unhelpful despite being short.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 24 parameters, multiple nested objects, and numerous sibling product tools, this description is completely inadequate. It provides no context about return values, effects, or how to use it effectively. With no output schema and minimal description, an agent would be hard-pressed to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all 24 parameters. The description provides no additional meaning, but the baseline for high coverage is 3. The description does not enhance parameter understanding, but it does not hurt it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Price by ID for a Product' is essentially a restatement of the tool name, providing no additional detail about what specifically is updated or how it differs from related tools like products_delete_price_by_id_for_product or products_get_price_by_id_for_product. It states a verb and resource but lacks the specificity to distinguish it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, context, or exclusions. An agent would have to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond what annotations already provide. It doesn't disclose side effects, required permissions, format of the sent document, or any post-send actions. Since annotations indicate readOnlyHint=false, the description at least aligns with a write operation, but it contributes nothing additional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but that is a symptom of under-specification rather than conciseness. It fails to earn its place because it adds no clarifying information. It is a single phrase with no structure or front-loading of key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects, no output schema) and the lack of description, the definition is completely inadequate. An agent cannot understand what the tool returns, what happens on success, or how to handle errors. The description is far too sparse for such a non-trivial operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the schema already documents most parameters. The description does not add any parameter value, but the baseline of 3 applies because the schema carries the weight. No additional clarification on medium, sentBy, or nested objects is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send document' states a verb and resource but is extremely vague. It doesn't specify what kind of document (proposal, contract, etc.), the destination, or the action's scope. It is essentially a restatement of the tool name and offers no differentiation from sibling tools like proposals_send_documents_contracts_template or proposals_list_documents_contracts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. An agent has no way to know if this is the right tool for sending a template or a specific document, or when to prefer the other send tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, indicating it's a write operation. The description adds nothing beyond that—no side effects, permissions, rate limits, or irreversible actions. It repeats the obvious fact that it creates a post without any additional behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a two-word phrase that is not even a complete sentence. It is under-specified, not concise in a useful way. There is no front-loaded information, no structure, and it provides no value beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 parameters, 3 required, nested objects, and platform-specific limitations (e.g., media constraints, follow-up comment restrictions), the description is completely inadequate. It omits any mention of accountIds, post type, scheduling, or platform-specific behavior. An agent cannot understand what a 'post' entails or what the expected outcome is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 17 parameters, so the schema already documents parameter meanings. The description itself contributes no parameter information, which is acceptable given high schema coverage. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create post' states a verb and a generic resource, but it does not specify that it's for social media posting, nor does it differentiate from sibling tools like social_media_posting_edit_post or social_media_posting_delete_post. It is only slightly more informative than the tool name itself, which already includes 'create_post'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, required fields, or exclusions. The description provides zero context for tool selection among the many social_media_posting_* siblings.
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?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context—no mention of return format, scope, or any side effects. It purely repeats the getter intent and contributes nothing beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short phrase, but conciseness should not sacrifice informativeness. 'Get Accounts' does not earn its place because it is vague and unhelpful. A longer, more specific description would be better. The structure is minimal but not useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single optional parameter and no output schema, the description is severely incomplete. An agent would not understand what is being retrieved, for which platform, or how it relates to other tools. The vagueness makes the tool nearly unusable without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter `locationId`, including its default behavior. The description adds no extra parameter information, so the baseline of 3 applies. The parameter is simple and well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Accounts' is a verb and resource but extremely vague. It does not specify which accounts (social media? platform-specific?) or distinguish itself from sibling tools like social_media_posting_get_facebook_page_group or social_media_posting_get_posts. An agent cannot reliably tell what this tool does from the description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many alternative getter tools. There is no mention of context, conditions, or exclusions. The description gives zero assistance in selection.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, implying a mutating operation, but the description adds no behavioral detail. It does not state what gets modified, whether the operation is idempotent (idempotentHint=false), what side effects occur, or what the response looks like. With no output schema and sparse annotations, the description fails to disclose any behavioral traits beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is under-specification rather than conciseness. It does not front-load any actionable information and provides no structure. It fails to earn its place because it conveys nothing beyond the tool's name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 7-parameter tool with 4 required parameters and no output schema, yet the description explains none of the purpose, flow, or constraints. An agent cannot correctly invoke this tool based on the description alone, especially given the broad sibling toolset. The description is completely inadequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so the parameters are well documented in the schema itself. The description adds no parameter-level meaning, but since coverage is high, the baseline of 3 applies. The description does not harm, but it also provides no additional clarification for ambiguous fields like 'accountIds' or 'rowsCount'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set Accounts' is a verb+resource but extremely vague. It does not specify what kind of accounts, what 'set' means (assign, configure, activate?), or how this differs from sibling tools like social_media_posting_attach_facebook_page_group or social_media_posting_set_google_locations. The title and description are nearly identical, so it reads close to a tautology and fails to convey a distinct purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context, prerequisites, or exclusions are mentioned. The description gives an agent no basis for deciding to call this tool over any other in the social_media_posting family.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety and idempotency profile. However, the description adds zero behavioral context—it does not mention what is returned, whether any side effects exist, or any edge cases. With no added context, the description contributes nothing beyond the annotations, so it fails to disclose anything not already implied by the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly one sentence, which is concise in word count, but it does not earn its place because it merely restates the tool name. It has no front-loaded information of value; the sentence is entirely redundant. True conciseness removes fluff while preserving meaning, but here the meaning is not enriched, so it is under-specification rather than effective brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and only one optional parameter, the description should at least clarify what the tool returns and what 'by location' implies. It does neither, leaving the agent unaware of the return shape or any nuance about location-based lookup. While the schema covers the parameter, the description's lack of return info makes the overall definition incomplete for an agent that needs to understand the tool's contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter locationId is fully described in the schema with 'Defaults to GHL_LOCATION_ID when omitted.' Schema coverage is 100%, so the baseline for this dimension is 3. The description adds no parameter-specific information; it only repeats the tool name. Since the schema is complete, the description does not need to compensate, and a score of 3 reflects that the schema carries the burden and the description offers no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is a verbatim tautology of the tool name and title: 'Get User by Location'. It provides no elaboration on what constitutes a 'user' in this context, what a 'location' refers to, or how this differs from sibling tools like users_get_user or users_search_users. Restating the name is the definition of a tautology, so the purpose is not clarified beyond the identifier itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to use this tool versus alternatives (e.g., users_get_user by ID, users_filter_users_by_email), nor any conditions that would make this the preferred choice. There is no mention of when not to use it or any prerequisites, leaving the agent with no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations only indicating basic flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description carries no additional behavioral context. It does not explain side effects, permissions, or what the creation actually entails, leaving agents blind to the operation's implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely brief, the description is under-specified rather than concise. It fails to convey any essential information, and this brevity undermines its utility. The two-word phrase is not an efficient summary but an empty placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 19 parameters, no output schema, and no behavioral disclosures, the description is completely inadequate. An agent has no information about return values, side effects, or how the response should be interpreted. This is a severe gap for a complex creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with each of the 19 parameters having detailed descriptions. The description adds nothing, but benefiting from the schema's richness, the baseline of 3 is appropriate. It neither helps nor hinders parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Agent' is essentially a restatement of the tool name, providing no detail beyond the verb and resource. It fails to distinguish from sibling tools like conversation_ai_create_agent or agent_studio_create_agent, making it a tautology rather than a clarifying statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description contains no guidance on when to use this tool versus alternatives, nor any prerequisites or context. An agent has no indication of the appropriate scenario for invoking this tool, making the guidance entirely absent.
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?
The description adds no behavioral information beyond what the name implies. The annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which already cover safety, but the description provides no additional context such as what data is returned, potential pagination, or any side effects. It relies entirely on the 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but this is under-specification rather than effective conciseness. While it is front-loaded and lacks fluff, it omits essential details about the tool's scope or behavior, making it insufficiently sized for the agent to understand its utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with a simple input schema and no output schema, the description fails to explain what 'audiences' encompasses, the return format, or any filtering capabilities. Given the existence of a sibling tool for fetching a single audience, it's unclear if this returns all audiences or a filtered set, leaving the agent without enough context to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a clear description for locationId (including its default), so with 100% schema description coverage, the baseline is 3. The tool description adds nothing about the parameter, so it does not enhance the schema's meaning, but it also doesn't need to given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get audiences' is a near-verbatim restatement of the tool name and provides no additional detail about what 'audiences' refers to (e.g., custom audiences, remarketing lists) or whether it returns a list. It does not differentiate this tool from the sibling ad_manager_google_get_audience_by_id, so the purpose is vague and ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as ad_manager_google_get_audience_by_id, ad_manager_fb_get_custom_audiences, or other ad platform tools. The description offers no context about selection criteria, prerequisites, or situations where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds no additional behavioral context, such as what gets deleted, side effects, or reversibility. It merely repeats the obvious destructive implication, offering no 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified at only two words, which is not conciseness but a lack of necessary detail. It does not front-load any useful information and omits critical clarifications about the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description is severely incomplete. It does not explain what a relation is, how to find relationId, what happens on deletion (soft vs hard delete), or any cascade effects. An agent cannot confidently call this tool without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 50%, the description should compensate for the undocumented relationId parameter, but it does not. It fails to explain what a relationId is, how to obtain it, or the meaning of the 'relation' concept. The description offers no parameter-level context, leaving the agent to work with an incomplete schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Relation' is essentially a rephrasing of the tool name without adding any information about what a 'relation' is or what it represents. It does not distinguish it from the sibling tool 'associations_delete_association', leaving the agent uncertain about the difference between a relation and an association.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like associations_delete_association or associations_create_relation. There is no mention of prerequisites, scenarios, or exclusions, so the agent has no basis to select this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to repeat that. However, it adds no context about what is destroyed (e.g., cascading effects, irreversibility, permission requirements), which would be expected for a destructive operation. It merely states the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is very short and front-loaded, it is under-specified rather than genuinely concise. It lacks essential context, making it ineffective despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with one required parameter and no output schema, the description is drastically incomplete. It fails to mention consequences, required permissions, or the meaning of businessId, leaving the agent without enough information to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage for businessId, and the description provides no explanation of what businessId refers to or how to obtain it. The description does nothing to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Business' is essentially a restatement of the tool name with no added detail. It lacks any differentiation from siblings like businesses_get_business or other delete tools, and provides no scope or specificity beyond the obvious action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, nor any prerequisites or conditions (e.g., whether the business must be unlinked first). The description does not help an agent decide between this and businesses_update_business or other delete tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=false (a write operation), idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond what annotations provide, such as side effects, required permissions, or irreversible changes. It does not contradict annotations, but it adds zero value on transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It lacks front-loaded scoping or key details. A single phrase 'Update Business' is not an informative summary; it is a label.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, no output schema, and no parameter descriptions, this tool requires substantial context to be used correctly. The description provides none, making it completely inadequate for an agent to understand what fields to update, how to structure the request, or what to expect in response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description mentions none of the 11 parameters. It does not even hint which fields are updatable or that businessId is required. The agent is left guessing about parameter meaning from type names alone, which is insufficient for a mutation tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Business' is essentially the same as the tool name, providing no additional specificity about what fields can be updated, what kind of business, or any scope. It is tautological and fails to differentiate from sibling tools like businesses_create_business or businesses_delete_business.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when it should not be used, or how it relates to other businesses_* tools. This leaves the agent to infer usage solely from the name and schema.
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?
The description gives no behavioral information beyond a generic create action. Annotations indicate readOnlyHint=false and destructiveHint=false, so the description does not contradict them, but it adds nothing about side effects, permissions, or consequences of a create operation. With annotations present, the bar is lower, but the description still contributes zero 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two words), but this is under-specification rather than effective conciseness. It saves space but at the cost of omitting all essential information, so it fails the structural test.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 54 parameters, no output schema, and complex sibling relationships, the description is grossly inadequate. It provides no information about required fields, constraints, or what the call returns. This is completely incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. While the schema covers 48% of parameters with descriptions, the description itself adds no meaning to any of the 54 parameters. The tool's complexity requires the description to compensate, but it doesn't, making parameter semantics completely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create Calendar'), so it clearly conveys the core action. However, it does not differentiate from sibling tools like calendars_create_calendar_group or calendars_create_calendar_resource, and it is essentially a restatement of the tool name. It is adequate but not distinguishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context about when it is appropriate, and no exclusions or notes about prerequisites. It is a bare statement of action with zero usage guidance.
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?
The description adds no behavioral context beyond what annotations already provide. Annotations indicate destructiveHint=true and readOnlyHint=false, but the description does not mention consequences, permissions, or any additional side effects. No added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse ('Delete Note'), which is not conciseness but under-specification. It lacks any structural elements like front-loaded context or clarifying phrases. It does not effectively serve its purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter destructive operation, the description should clarify what the tool acts on and any relevant context. It fails to mention that it's an appointment note, nor does it reference the parent appointment. The annotations cover destructive behavior, but the description is too thin to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both appointmentId and noteId are documented in the schema. The description adds no additional meaning, but the baseline of 3 applies because the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Note' provides a verb and a generic resource, but lacks specificity about what note (appointment note) is being deleted. It does not distinguish from other delete tools in the same domain, such as calendars_delete_calendar_resource or calendars_delete_event. The name itself adds context, but the description does not clarify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, context, or conditions under which it should be selected over similar delete tools. Completely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint false, destructiveHint false, and idempotentHint true, which provide some safety profile. The description adds nothing beyond the name; it does not explain the semantics of 'disable' (e.g., setting isActive to false), potential side effects, or permissions. Since annotations cover the basic safety traits, the description's failure to add any behavioral context keeps it at a minimal score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two words) but not appropriately concise—it's under-specified. It lacks essential context and does not front-load key information. This is not genuine conciseness but rather a failure to provide necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only two required parameters and no output schema, the description is entirely insufficient. An agent cannot understand what the tool does, what 'disable' means, or how it relates to other group operations. Even for a simple tool, the description fails to convey the tool's purpose and usage effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the two parameters, so the baseline is 3. The schema briefly describes 'Group Id' and 'Is Active?' which is minimal but present. The description does not enhance parameter understanding; it doesn't clarify that isActive=false corresponds to disabling. This is acceptable given the schema covers all parameters, but no extra value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Disable Group' is a near-tautology of the tool name 'calendars_disable_group'. It restates the name without specifying what a 'group' is in this context (calendar group?), how disabling differs from other group operations like edit or delete, or what the effect of disabling is. It fails to distinguish from sibling tools such as calendars_edit_group or calendars_delete_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any conditions, prerequisites, or exclusions. An agent cannot determine whether to call this instead of calendars_edit_group or calendars_delete_group based on the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the verb 'Update'. Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true, which cover the safety profile. The description does not add anything about side effects, required permissions, or what specifically changes. It neither contradicts the annotations nor enriches them, so it offers minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Running at just two words, the description is under-specified rather than concise. It does not form a complete sentence and provides no useful content. While it is short, it does not earn its place because it conveys almost no information that an agent would need.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four required parameters, a low schema coverage, and no output schema, the description must carry substantial contextual weight. It fails to do so — it does not explain what the tool does beyond 'Update Group', does not clarify that all fields are required, and does not describe any update behavior or constraints. This is far too incomplete for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% — only groupId has a description ('Group Id'). The other three parameters (name, description, slug) have no schema descriptions. The tool description 'Update Group' does not explain any parameter semantics, nor does it compensate for the low coverage. An agent would have no additional information about what name, description, or slug mean or how they relate to the update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Group' names a verb and a resource, but it is vague — it does not specify 'calendar group' or mention any fields to update. It is not a tautology, but it lacks the specificity needed to clearly distinguish this from other group-related tools. A minimal viable statement, but not a clear one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as calendars_create_calendar_group or calendars_validate_groups_slug. The description gives no context, no prerequisites, no exclusions, and no mention of alternative tools. No usage guidance is provided at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, implying a mutating but not destructive operation. However, the description adds no behavioral details beyond that. It fails to disclose side effects, such as whether the operation is idempotent (idempotentHint=false), what happens if a contact is already associated or not associated, or any prerequisites. The description provides no 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but brevity is not appropriate here because it omits essential information. It is under-specified rather than concise, providing no structure or front-loaded clarity. A single ambiguous phrase cannot be considered well-structured when crucial details are missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that performs two distinct actions (add and remove) without an explicit action parameter, the description is severely incomplete. It lacks information on how to indicate the operation, what the response looks like, any constraints, or behavioral nuances. With no output schema and only two required parameters, the agent cannot correctly invoke this tool without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only locationId has a description), and the description does not explain any of the parameters. Particularly, it does not clarify how 'ids' and 'businessId' are used or how the add/remove behavior is controlled through these inputs. With low schema coverage, the description should compensate, but it offers nothing, leaving the agent to guess the meaning and usage of required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add/Remove Contacts From Business' essentially restates the tool name, providing no additional clarity. It combines two actions without explaining what distinguishes adding from removing or how the tool determines which operation to perform. The verb and resource are present, but the ambiguity makes it barely more informative than a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The sibling list includes contacts_add_contact_to_campaign and contacts_remove_contact_from_campaign, which are similar operations, but the description does not differentiate them or explain the context for adding/removing contacts to/from a business. There is no information about when add vs remove is appropriate or how to specify the action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide some baseline (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), but the description adds almost nothing beyond the word 'Add'. It does not disclose whether tags are appended or replaced, whether existing tags are affected, or any side effects. The description fails to enrich the behavioral profile beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is merely two words, which is not concise but under-specified. It fails to earn its place by conveying any useful information. A good concise description would still be short but include the resource and key behavior. This is an abbreviation, not a structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation, one might argue the schema and name suffice, but the description is so minimal that it leaves important ambiguities (e.g., target entity, behavior with existing tags). With no output schema, the description should have explained what happens upon success, but it does not. The description is not complete enough for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: only contactId has a description ('Contact Id'); tags has none. The tool description does not compensate for the missing parameter semantics. It does not explain the format of tags (e.g., string list of tag names), acceptable values, or relationships. With low schema coverage, the description should have stepped in but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add Tags' is extremely vague. It states the action (adding) and the object (tags) but does not specify the target resource (contact). The tool name 'contacts_add_tags' implies the target, but the description itself fails to distinguish this from adding tags to other entities. It does not differentiate from siblings like 'contacts_remove_tags' beyond the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance whatsoever. The description provides no context on when to use this tool versus alternatives such as 'contacts_remove_tags' or other contact modification tools. There is no mention of prerequisites, scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and idempotentHint=true, so the agent knows it is destructive and idempotent. However, the description adds no behavioral context beyond this—it does not mention that the action is permanent, what happens to the contact's progress, or any additional effects. Since annotations already provide the safety profile, a score of 2 reflects that the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase, which is overly terse rather than concisely informative. It lacks even a full sentence to provide context. While brevity is generally good, here it results in under-specification, making the description unhelpful for an agent understanding the tool's purpose and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, this description is incomplete. It does not inform the agent about the effect on the contact, whether the contact is removed from the entire workflow or just a specific step, or any follow-up actions. The absence of an output schema and minimal description leaves significant gaps for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (contactId and workflowId have descriptions; eventStartTime does not). The description adds no information about any parameter, especially the optional eventStartTime, which is entirely unexplained. It relies solely on the sparse schema descriptions, and the missing third parameter remains a mystery without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Contact from Workflow' is essentially a restatement of the tool name. It conveys the action (delete) and the object (contact/workflow) but adds no specifics about what this operation entails, such as whether it removes the contact from all workflow steps or has any side effects. It does not differentiate from similar delete operations like contacts_remove_contact_from_campaign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like contacts_add_contact_to_workflow, contacts_remove_contact_from_campaign, and contacts_remove_contact_from_every_campaign, the description gives no hint about the appropriate context, prerequisites, or how it differs from those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=false, so the description's 'update' adds no new behavioral information. It does not mention side effects, whether existing values are replaced entirely, or what happens if the redirect ID does not exist. No contradiction, but also no added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal and could be considered concise, but it is under-specified to the point of being unhelpful. It front-loads nothing beyond the tool's name. Effective conciseness requires the right amount of content; here it is just a placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters and no output schema, the description fails to provide essential context: what a redirect is, what target and action represent, how locationId factors in, or any typical use case. An agent would have to infer everything from parameter names, which is insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation for any of the four parameters. With schema description coverage at only 25% (only locationId is described), the burden falls on the description to clarify meanings of id, target, and action, but it does nothing. The enum for action is self-explanatory, but target and the relationship between fields remain opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Redirect By Id' essentially restates the tool name and title, providing no additional specificity about what fields are updated or how this differs from related redirect operations like create or delete. It is a tautology rather than an explanatory statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus funnels_create_redirect or funnels_delete_redirect_by_id. There is no mention of prerequisites (e.g., obtaining the redirect ID from funnels_fetch_redirects_list) or any conditions for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows it is a non-read-only operation. However, the description adds no further behavioral context, such as permissions required, what gets created, or any side effects. It simply restates the verb, contributing nothing 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but under-specified. It is a single phrase that does not earn its place because it offers no information beyond the name. This is not effective conciseness but rather underspecification, similar to the 'Process' example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—19 parameters, nested objects, no output schema—the description is severely inadequate. It does not explain what an invoice schedule is, how the schedule object should be structured, or what the expected result might be. An agent has no context to construct a correct request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 47% (low), the description should compensate by explaining key parameters or their relationships. It provides none. The description is silent on all 19 parameters, leaving the agent to rely on a partially documented schema. No value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Invoice Schedule' is essentially a restatement of the tool name, with no additional specifics about scope, fields, or behavior. It does not distinguish the tool from siblings like 'invoices_create_invoice' or 'invoices_schedule_invoice_schedule', making it a tautology that adds no new meaning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever about when to use this tool versus alternatives. No mention of prerequisites, side effects, or exclusions. An agent has to infer from the name alone, which is insufficient for selecting among many invoice-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no behavioral context beyond these hints—it merely repeats the name. It doesn't explain what happens to existing data, whether the update is partial or full, or any side effects. Since annotations already carry some safety hints, the description could compensate with useful details but doesn't.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely under-specified, not concise. Two words convey almost no information. While it is front-loaded (if one considers it front-loaded as the only content), it fails to provide essential context. Its brevity is a deficiency rather than an asset.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is an update operation with three required parameters and no output schema, the description is grossly incomplete. It doesn't explain what a link is, what fields are updatable, what happens if parameters are omitted, or any edge cases. An agent would have little idea how to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description makes no mention of parameters. The schema covers only 33% of parameters with descriptions (only linkId has a description). With low schema coverage, the description should have elaborated on what 'name' and 'redirectTo' represent or any constraints, but it does not. No value is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update Link', which identifies the action and resource but lacks specificity about what fields can be modified or how it differs from sibling tools like links_create_link or links_delete_link. It's not a pure tautology (the tool name is links_update_link vs. 'Update Link') but it's close and provides only minimal clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, scenarios, or exclusions. The description is purely declarative and offers no context for selection among the many link-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the annotations (readOnlyHint=false, so a mutation is expected), but it adds no behavioral details beyond the annotations. It does not mention any side effects, permissions, or reversibility, so it contributes nothing beyond what structured fields already communicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse (three words), which is under-specification rather than effective conciseness. It lacks any explanatory structure, so the brevity is not a virtue here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, three parameters, and a minimal description, the tool definition is severely incomplete. An agent would not know what this tool does, what the parameters mean, or what to expect, making it nearly unusable without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 33% description coverage (only locationId has a description), and the tool description provides no parameter information. The meaning of 'name' and 'value' is entirely undocumented, and the description does not compensate for this gap at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Custom Value' essentially restates the tool name without providing any additional specificity about what a custom value is or how it relates to locations. It does not distinguish this tool from siblings like locations_create_custom_field or locations_create_tag, making the purpose vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description gives no context about the use case, prerequisites, or scenarios where this tool is appropriate, leaving the agent without clear direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the agent knows this is a write operation that is non-destructive and idempotent. The description adds nothing beyond these—no mention of required fields, side effects, or return behavior. It neither contradicts nor enriches 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a three-word fragment—but this is under-specification rather than effective brevity. For a tool with 10 parameters and a nontrivial purpose, the description should convey more useful context. It is not structured to front-load key information because there is almost no information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, low schema coverage, no output schema), the description is woefully incomplete. It provides no context on when to use it, what fields are required, or what the outcome is. An agent has insufficient information to call this tool correctly without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 30%, with most parameters undocumented. The description provides no parameter details or hints about what values are expected, failing to compensate for the low coverage. An agent would have to rely solely on the schema, which lacks descriptions for many fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Custom Field' states a clear action and resource, distinguishing it from create/delete/get siblings. However, it lacks any detail about the scope (locations) or which attributes can be updated, and it doesn't differentiate itself from other 'update' tools in the same domain (e.g., locations_update_tag). The verb+resource is explicit but minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like locations_create_custom_field or locations_delete_custom_field. There is no mention of prerequisites, conditions, or when an update is appropriate. This is completely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the basic action. While it aligns with the readOnlyHint=false annotation, it adds no context about side effects, requirements, or response 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely under-specified—a single phrase that adds no value. It is not a concise, well-structured definition but rather a placeholder that fails to earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, nested objects, required fields), a one-word description is completely inadequate. It provides no context about usage, configuration, or implications, leaving the agent with no guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no parameter-specific meaning, but the baseline of 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.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Coupon' is a tautology that merely restates the tool name. It fails to distinguish this tool from sibling tools like payments_update_coupon or payments_delete_coupon, offering no additional specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention context, exclusions, or reasons to choose this over related coupon operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the agent knows this is a safe read. However, the description adds no behavioral context beyond a tautological restatement of the name—no mention of pagination, results scope, or data source behavior. Since annotations cover the safety profile, the description's lack of extra context warrants a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (3 words), but this is under-specification rather than concise efficiency. It omits essential details and does not earn its place because it conveys almost nothing useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description should at least indicate what is returned (e.g., a list of audiences) and any important filtering or scoping behaviors. It does none of this, making it inadequate for an agent to call correctly without opening the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 4 parameters (100% coverage), including enums for type and source. The description adds no meaning beyond the schema, so per the rubric, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get custom audiences' states a verb and resource, but it's vague and doesn't distinguish this tool from siblings like ad_manager_fb_get_custom_audience_by_id or ad_manager_fb_get_entity. It fails to specify whether this lists all audiences or a specific one, so an agent can't tell when to use this vs alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool or what differentiates it from related tools. No mention of alternatives, filtering conditions, or prerequisites, leaving the agent to guess based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description 'Get reporting data' is consistent with these but adds no additional behavioral context. It does not mention any authentication requirements, rate limits, pagination, or what data is actually returned. With annotations covering safety, the description should add value but does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
'Get reporting data' is extremely short, but this is under-specification rather than effective conciseness. There is no front-loading of critical information, and the single phrase does not earn its place by conveying any actionable detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters (5 required) and no output schema, this description is completely inadequate. It does not explain what the report contains, how to interpret the fields, whether there are required date ranges, or any limitations. An agent is left to infer everything from the schema, which is insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – every parameter has a description in the input schema (e.g., 'Time grouping interval', 'Comma-separated reporting fields'). The description itself adds no meaning beyond the schema, so the baseline 3 applies. It does not help with nuances like date format or field constraints beyond what the schema already lists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get reporting data' is extremely vague. It does not specify what kind of reporting data, from which ad platform (though the name implies Facebook), or how it differs from sibling tools like ad_manager_fb_get_campaign_reporting or ad_manager_fb_get_reporting_list. It barely states a verb and resource without any specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context, prerequisites, or exclusions are provided. An agent has no way to know if this is the right tool for a given reporting scenario without opening the schema and guessing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond the annotations. Annotations indicate a non-read-only, non-destructive, open-world operation, but the description does not elaborate on side effects, what 'publishing' means operationally, or potential failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, the brevity is not effective; the single sentence adds no value over the tool name and fails to convey essential details. It is under-specified rather than concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating operation like publishing a campaign, the description is completely inadequate. It doesn't explain the effect of publishing, whether it requires an existing integration, or what happens on success. The output is unknown, and no context is given.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents both parameters (campaignId and locationId) with clear descriptions, so the baseline applies. The tool description does not add any parameter-specific information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Publish campaign' simply restates the tool name's last two words, providing no additional clarity about what publishing entails or how it differs from other campaign operations (e.g., upsert, duplicate). It is essentially a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus any of its many siblings (e.g., ad_manager_fb_upsert_campaign, ad_manager_fb_pause_campaign). There is no mention of prerequisites, context, or alternatives.
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?
The description adds no behavioral detail beyond what the annotations already convey. Annotations indicate readOnlyHint=false (write operation), destructiveHint=false, and idempotentHint=false, but the description simply repeats the action verb without explaining side effects, asynchronous behavior, or any constraints. No additional context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief—one sentence that mirrors the tool name. While it is concise in length, it is under-specified and provides no value beyond the name, so it fails the 'every sentence earns its place' test. This is not effective conciseness but rather under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no required fields, no output schema, and minimal annotations, the description is grossly inadequate. It does not explain what an 'offline user list job' is, what inputs are needed, what happens after creation, or any expectations about the CSV format or list types. An agent has almost no information to correctly use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a short description (e.g., 'CSV file path', 'Dynamic list flag'). The description itself adds no parameter information, but since the schema already documents all parameters, the baseline of 3 is appropriate. The tool description does not compensate for any missing param context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create offline user list job' is essentially a restatement of the tool name (ad_manager_google_create_offline_user_list_job), offering no additional specificity about what the job entails or how it differs from sibling ad_manager_google tools. It is a tautology rather than a clarifying statement of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like ad_manager_google_upsert_audience or ad_manager_google_get_audiences. The description does not mention prerequisites, conditions, or situations where this tool is the appropriate choice, leaving the agent without contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered by structured data. However, the description adds no further behavioral context: no mention of what data is returned, whether it requires an active integration, or any rate-limit/pagination behavior. It contributes nothing beyond the annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but this is under-specification rather than conciseness. For a reporting tool with multiple required parameters and many siblings, this is far too terse to be useful; it sacrifices essential detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high number of sibling reporting tools and the absence of an output schema, this description is seriously inadequate. It does not explain what metrics are returned, how dates are formatted, whether timezone matters, or what the difference is from get_reporting or get_reporting_list. An agent cannot correctly invoke this tool based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter documented (startDate, endDate, campaignId, locationId with a default). The description itself adds no parameter semantics, but since the schema is complete, the baseline of 3 is appropriate—the structured data carries the informational load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get campaign reporting' is nearly tautological, restating the tool name without specifying what metrics, scope, or ad platform details are included. It does not differentiate from sibling tools like ad_manager_google_get_reporting or ad_manager_google_get_reporting_list, so an agent cannot tell which reporting tool to choose without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many sibling reporting tools (e.g., ad_manager_fb_get_campaign_reporting or ad_manager_google_get_reporting). No mention of prerequisites, integration requirements, or whether it pertains to a specific ad platform beyond the name. Entirely unhelpful for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. However, the description adds no additional behavioral context such as return format, pagination, filtering behavior, or side effects. The description does not contradict annotations (annotation_contradiction=false), but it contributes nothing beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Get conversions'), but it is under-specified rather than efficiently structured. It front-loads nothing useful and lacks any elaboration. While brevity is good, a two-word description provides no structural value; it is closer to a tautology than a helpful summary. It does not earn its place because it adds almost no information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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, and a complex domain (ad manager with many siblings), this description is severely incomplete. There is no mention of required vs optional parameters, default behavior (e.g., locationId defaults to GHL_LOCATION_ID), what data is returned, or how it relates to other conversion-related tools. An agent cannot reliably determine scope, constraints, or expected outcomes from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 6 parameters (100% coverage), so the baseline for schema coverage is 3. The description itself does not add any parameter semantics—it does not mention filters, date ranges, types, or defaults. Since the schema already covers each parameter clearly, the description adds no extra meaning but is not penalized heavily because the schema is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get conversions' is a very generic verb+resource statement but lacks specificity. It does not specify what kind of conversions (ad conversions, conversion goals, etc.), which platform (Google is implied by the name but not stated), or how it differs from siblings like ad_manager_google_get_conversion_by_id or ad_manager_google_get_conversion_goals. It is not a tautology but is minimally informative and fails to distinguish the tool within its context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description provides no context about prerequisites, intended scenarios, or exclusions. Sibling tools with similar names (e.g., get_conversion_by_id, get_conversion_goals) are not mentioned, leaving the agent to infer usage without any support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond these annotations—it doesn't mention what the reporting list contains, whether it returns any data, or any other operational detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief—a single vague sentence. While it is concise, it is under-specified and fails to provide useful information. The brevity is not a virtue here because it omits essential operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 required parameters, no output schema, and no description of return format or behavioral details, the description is grossly inadequate. The agent cannot infer what the tool returns, how to interpret the parameters, or what to expect when calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description in the input schema (e.g., type enum, startDate, endDate, listType). The tool description adds nothing beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get reporting list' is a vague restatement of the tool name without specifying the platform (Google), the nature of the reporting list, or how it differs from sibling tools like ad_manager_google_get_reporting or ad_manager_fb_get_reporting_list. It identifies a resource but offers no distinguishing context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description provides no context for when this tool is appropriate, nor does it exclude any scenarios. An agent has no information to decide between this and the numerous related reporting tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description has a lower burden. However, it adds no behavioral context—it does not state what the tool returns (e.g., a list of targeting options) or any other operational detail. It doesn't contradict annotations, but fails to provide useful transparency beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short noun phrase, which is technically concise but severely under-specified. It lacks a verb, any qualifying detail, or structured information. A proper concise description would combine an action and object (e.g., 'Retrieves Google Ads search targeting options'), but this merely restates the tool's name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only source of information about what the tool returns. It fails to describe the return value, the meaning of the required 'type' parameter, or any other context. An agent could not correctly call this tool without substantial external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter has a basic description. The tool description itself does not elaborate on parameters or their relationships, relying entirely on the schema. This meets the baseline for high coverage but adds no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search targeting options' lacks a verb, making it ambiguous whether the tool retrieves, lists, or searches for targeting options. The name implies Google search targeting, but without an explicit action, an agent cannot clearly distinguish this from similar tools like ad_manager_fb_search_targeting or ad_manager_li_search_targeting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, when not to use it, or how it differs from alternatives. The description does not mention that it's for Google Ads or that it should be used to fetch targeting options. The agent would have to infer usage from the name alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false, but the description adds no explanatory context. It does not state that an existing segment will be updated or a new one created, nor does it mention required authentication or side effects. With annotations present the bar is lower, but the description still fails to add behavior beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, this is not conciseness but severe under-specification. It fronts no useful information and forces the agent to open the schema to learn anything. While concise in length, it sacrifices all value, and the calibration rubric explicitly treats under-specification as a failure, not conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters, nested objects (ruleBasedUserList), enums, and no output schema, the description is grossly inadequate. It does not explain what a segment is, how to choose among segment types, what the fields mean in context (e.g., members for CUSTOM_SEGMENTS vs seedUserListIds for LOOKALIKE), or what the response represents. This is a complex tool requiring rich guidance that is entirely absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 13 parameters have descriptions and the schema carries full semantic weight. The description provides no parameter context, but per the rubric, the baseline is 3 when schema coverage is high. It does not add or contradict anything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('Upsert segment'), but it is essentially a rephrase of the tool name with no additional context about what a segment is or how it differs from sibling tools like ad_manager_google_upsert_audience. It does not clarify whether a segment refers to a remarketing, custom, or other Google Ads entity, leaving purpose ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, when to create vs update, or how this relates to the many other ad_manager_google_upsert_* and ad_manager_google_delete_segment tools. The description provides zero decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. However, the description adds no behavioral context beyond 'Get ad analytics'—it does not mention any default behavior (like locationId defaulting to GHL_LOCATION_ID), return format, pagination, or other side-effects. Given the low bar because annotations already cover safety, the description still fails to add meaningful behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Get ad analytics') but this is under-specification rather than effective conciseness. It does not front-load any important detail; it merely restates the tool name. The single sentence does not earn its place because it adds no value over the name itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and a large set of sibling analytics tools, this description is wholly inadequate. It does not explain what analytics are returned, how to interpret the response, or how this tool differs from ad_manager_li_get_campaign_group_reporting, ad_manager_li_get_reporting_list, and similar. An agent cannot correctly select or invoke this tool based on this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—all seven parameters have descriptions, including date formats, enums for pivot and groupBy, and defaults for locationId. The description itself adds nothing beyond the schema. Since schema coverage is high, the baseline of 3 applies, and no extra credit is warranted because the description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('Get') and a resource ('ad analytics') but is extremely generic. It does not specify what kind of analytics, which ad platform, or how it differs from siblings like ad_manager_li_get_campaign_group_reporting or ad_manager_li_get_reporting_list. It essentially restates the tool name with minimal added detail, making it difficult for an agent to distinguish among the many analytics-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus any of the numerous sibling reporting/analytics tools. There is no mention of conditions, alternatives, or exclusions. An agent has no help deciding between this and ad_manager_lt_get_campaign_group_reporting, ad_manager_google_get_reporting, etc.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description only repeats the action 'update' without adding detail about side effects, required permissions, or what happens to the ad object. It does not contradict annotations, but it contributes nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is structurally simple, but it is so terse that it sacrifices informativeness. It lacks meaningful content, making it under-specified rather than concise in a productive way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters (2 of which are enums), no output schema, and multiple related siblings, this description is woefully incomplete. It does not explain the effect of each operationType, which entity types are supported, or any expected response. An agent would struggle to call this correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all parameters (100%), providing basic meanings like 'Ad identifier', 'Ad object type', and 'Update operation'. The tool description adds no extra nuance about parameter relationships or how they interact (e.g., that 'operationType' values map to specific status changes). Given full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update ad status' is extremely vague. It does not specify that this operates on LinkedIn ad objects, nor does it clarify that it can target ad groups, campaigns, or ads (as indicated by the 'type' parameter). It fails to differentiate from sibling tools like ad_manager_fb_pause_ad or ad_manager_google_publish_ad, which also update statuses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description gives no indication of when to use this tool versus alternative ad management tools (e.g., for LinkedIn specifically, or for pausing vs. resuming vs. archiving). The name hints at LinkedIn, but the description itself offers no direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds nothing beyond the annotations. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so safety is covered. However, there is no disclosure about pagination, response structure, or any side effects (though none expected). The description is too thin to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which could be seen as concise, but it is under-specified to the point of being a placeholder. It lacks structure for presenting essential information like usage or parameter details. The 'Deprecated' note is stuck in parentheses without context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description is far from complete. It does not explain what the returned data looks like (no output schema), does not mention pagination despite having limit/offset parameters, and does not provide any context about the 'source' parameter. The description is inadequate for an agent to call this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. The input schema only documents 'locationId' with a default note, and the other three parameters (limit, offset, source) are completely undocumented in either schema or description. Given low schema coverage (25%), the description should compensate but does not provide any parameter context whatsoever.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('List') and resource ('Agents'), which is clear. However, it is essentially a restatement of the tool name and does not differentiate from the non-deprecated sibling 'agent_studio_get_agents'. Adding a note about deprecation is minimal and does not explain what kind of agents or any specifics beyond a generic list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool or when to prefer the alternative (e.g., agent_studio_get_agents). The 'Deprecated' marker is not actionable; it does not direct users to a replacement or explain why this version is deprecated. Zero usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, so the description need not restate those. However, it adds no behavioral context: it does not disclose what happens if a duplicate key is used, whether the operation is reversible, what validation occurs on the object keys, or whether any side effects (e.g., notifications) are triggered. The description is silent, leaving the agent with only the schema's parameter hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is extremely concise but not usefully so. It front-loads nothing substantive; it is an under-specification rather than a well-structured summary. A good description would mention the purpose (linking two objects) and perhaps the key constraint. This is too sparse to serve as an agent-facing guide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (5 required), no output schema, and nested objects, the description is severely incomplete. It fails to explain what constitutes an 'association' in this system, how to structure the firstObjectKey/secondObjectKey (e.g., what keys are expected), what labels 'custom_objects.children' and 'contact' represent, or how the tool behaves in edge cases. An agent cannot correctly construct a valid request using only this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 6 parameters (100% coverage), including meaning for 'key' and labels. The description itself contributes no additional parameter semantics. Per the rubric, with high schema coverage, the baseline is 3. The schema descriptions are terse (e.g., 'First Objects Key' and 'First Objects Association Label'), but they do convey basic intent, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Association' is a near-verbatim restatement of the tool name. It names the action and resource but gives no specification of what an 'association' is, which objects it links, or how it differs from sibling tools like associations_create_relation, associations_update_association, or associations_delete_association. Without reading the schema, an agent cannot differentiate this tool from other association tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides zero guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., object schemas must exist), typical scenarios, or any conditions under which a different tool (like associations_get_association_by_id or associations_create_relation) would be more appropriate. No exclusions or recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide substantial behavioral information (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds nothing beyond a bare statement, providing no context about default location behavior, pagination, or what is returned. Since the description adds no value beyond annotations, this scores low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence), which is efficient but under-specified. It lacks necessary detail to be considered well-structured. While it is front-loaded, it does not earn its place by conveying any useful information beyond the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values and any important behaviors. It does neither. The tool has 5 optional parameters with implications (pagination, filtering, location defaulting), none of which are mentioned. The description is completely inadequate for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions (100% coverage). Per the rubric, a baseline of 3 is appropriate when the schema fully documents parameters. The description contributes no additional semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Brand Boards' is essentially a restatement of the tool name. It names a verb and resource but does not specify the 'by location' aspect or how this differs from sibling tools like brand_boards_get_brand_board_by_id. It lacks the specificity needed to distinguish this tool from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not indicate contexts where this tool is appropriate, nor does it mention any exclusions or prerequisites. An agent is left to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only operation and no destructive intent, but the description adds no behavioral context. It does not disclose what happens on creation, any side effects, permission requirements, or the returned value. With annotations present, the bar is lower, but the description provides zero additional transparency beyond the 'create' implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is concise but not appropriately sized; it under-specifies the tool. There is no structure, no meaningful content, and no front-loaded information. The description is effectively a tautology that restates the verb and object without adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with three parameters and no output schema, this description is completely inadequate. It provides no context about preconditions, related entities, error scenarios, or expected results, leaving an agent unable to call the tool with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameters. The schema itself describes 'body' and 'appointmentId' briefly, but 'userId' has no description. Since schema coverage is 67% (not >80%), the description should compensate but does not, offering no clarification of parameter meaning, format, or optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Note' states a verb and a generic resource but omits the appointment context entirely. It fails to distinguish this tool from sibling tools like calendars_delete_appointment_note or contacts_create_note, and an agent cannot tell what kind of note this creates without inspecting the name or schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives (e.g., calendars_update_appointment_note or contacts_create_note). No context, exclusions, or prerequisites are provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows it's a destructive operation. However, the description adds no additional context such as permanence, side effects, or that the deletion is irreversible. It merely repeats the action without enriching the behavioral profile 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words, which is concise but drastically under-specified. It is not 'appropriately sized' because it fails to convey essential information beyond the tool name. It has no structure and does not front-load any useful detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with destructive behavior and no output schema, the description is wholly inadequate. It provides no information about return values, errors, prerequisites, or what the deletion entails. An agent cannot fully understand the operation's effect or requirements from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters (id and contactId) with clear descriptions, so schema coverage is 100%. The description adds no extra meaning about how these parameters relate or are used, but since the schema does the job, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Note' states a verb and resource, but it is extremely terse and does not specify the context (e.g., deleting a note from a contact). It does not distinguish well from other delete tools like contacts_delete_contact. It is nearly a tautology and lacks sufficient specificity for an agent to understand the exact scope without inferring from the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives, nor any prerequisites, exclusions, or context about the intended use case. An agent receives zero direction on selecting this over other note-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds zero behavioral context beyond that — no mention of pagination defaults, return format, filtering behavior, or any non-obvious side effects. With annotations covering safety, the description still fails to add meaningful transparency about what 'Get Contacts' actually returns or how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
'Get Contacts' is extremely short but under-specified rather than effectively concise. There is no structure, no grouping of information, and no front-loading of key facts. The description wastes the opportunity to add any useful guidance, so it fails the 'every sentence should earn its place' test because it has no substance at all.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters, no output schema, and no nested objects, the description provides no overview, no explanation of how parameters interact, no pagination defaults, and no mention of what the returned data represents. An agent cannot infer the correct usage or expected results from this description alone. Complete inadequacy for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (limit, query, locationId, startAfter, startAfterId) has a description. The tool description itself adds no parameter information, but the baseline of 3 applies because the schema already documents them adequately. No extra value is provided by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Contacts' merely repeats the tool name (contacts_get_contacts) and adds no specification of scope or distinction from siblings. It doesn't clarify whether this retrieves all contacts, supports filtering, or how it differs from contacts_get_contact, contacts_get_contacts_by_business_id, or contacts_search_contacts_advanced. It is a tautological restatement of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are many sibling tools for contacts (e.g., contacts_get_contact, contacts_search_contacts_advanced), and the description doesn't mention any conditions, exclusions, or alternative routes. An agent would have no basis to select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no behavioral detail such as pagination, filtering constraints, or response characteristics. It does not contradict annotations but contributes nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is under-specced rather than concise. While it is front-loaded, it lacks any substantive information. Every word earns its place, but there are almost no words, so the structure is too sparse to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an advanced search tool with a single opaque body parameter and no output schema, the description is completely inadequate. An agent has no idea what filters are supported, how to construct the request body, or what results to expect. The description fails to provide even minimal context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'body' parameter, which is described as 'Request body as defined by the HighLevel API.' The description itself adds no parameter explanation, but the baseline is 3 because the schema already covers the parameter. There is no enhancement from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Contacts' states a verb and resource but is extremely vague. It does not explain what makes this 'advanced' or how it differs from sibling tools like contacts_get_contacts or contacts_search_contact. The purpose is clear in the broadest sense but lacks the specificity needed for an agent to distinguish it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context about use cases, prerequisites, or why 'advanced' search would be preferred over other contact search tools. The description provides zero orientation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the operation to be non-read-only, idempotent, and non-destructive, but the description adds nothing beyond that. It does not explain what happens during the update, such as whether fields are overwritten individually or all at once. With annotations present, the description still contributes no additional 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The two-word description is under-specification, not conciseness. It is not front-loaded with essential information because it contains none. There is no structure or prioritization of the most important aspects an agent needs to know.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (21 parameters, nested objects, no output schema), this description is grossly incomplete. An agent cannot infer how to call this tool correctly, what to pass, or what to expect. It is fundamentally inadequate for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers only 19% of parameters with descriptions, and the tool description mentions none of them. For a tool with 21 parameters, the description should at least hint at common fields or usage patterns, but it does not. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Contact' essentially restates the tool name, adding no new information about what the update entails. It is a tautology that fails to distinguish this from sibling tools like contacts_upsert_contact or contacts_create_contact. The verb and resource are clear, but no specifics are provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as upsert or create. The description offers no context on prerequisites, scenarios that warrant an update, or when another contact tool would be more appropriate. An agent is left guessing about tool selection.
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?
The description adds no behavioral information beyond what the annotations already provide. The annotations indicate readOnlyHint=false and idempotentHint=false, and the description simply restates the creation action without disclosing side effects, required permissions, or consequences. It provides no value beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single terse phrase that doesn't constitute a meaningful sentence. While it's concise, it is under-specified and fails to provide any useful content. Every word should earn its place, but here the words 'Create' and 'Custom Field' merely echo the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters, 5 required, and no output schema, the description is grossly inadequate. It provides no overall context about what a custom field is, how objectKey and fieldKey relate, when to use this over other creation tools, or what the response will look like. The schema alone cannot compensate for the complete lack of domain guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 13 parameters have detailed descriptions in the input schema. The tool description itself adds no parameter meaning, but the baseline of 3 applies because the schema already documents parameters thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Custom Field' states a clear verb and resource, but it's extremely generic and doesn't specify what a custom field is or how it differs from related tools like custom_fields_create_custom_field_folder. It's more than a pure tautology because 'custom field' is a specific entity, but it lacks any differentiating detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as custom_fields_update_custom_field or custom_fields_create_custom_field_folder. There is no mention of prerequisites, conditions, or exclusions. An agent has no information to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. However, the description adds no behavioral context whatsoever—nothing about return format, pagination behavior, or what 'campaigns' refers to. With the low bar set by existing annotations, this still fails to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but severely under-specified. It lacks essential details about the tool's purpose, scope, or usage, making it more of an under-specification than a well-structured concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 11 optional parameters and no output schema, the description is completely inadequate. It does not explain what the tool returns, what constitutes a campaign, or how to interpret the results. An agent would have no idea what to expect from calling this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 11 parameters having a descriptive entry. The description does not add any parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Campaigns' states a verb and resource but is extremely vague. It does not specify that these are email campaigns, nor does it distinguish this tool from the sibling 'campaigns_get_campaigns'. The tautological phrasing merely restates the tool name without adding clarity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives. No mention of when the filtering parameters are useful, no exclusions, and no reference to similar sibling tools like campaigns_get_campaigns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description only says 'Delete', which is consistent. However, it adds no extra behavioral context such as whether deletion is permanent, if it can be undone, or any side effects. Since annotations cover the core safety signals, the description contributes little beyond what is already known.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but this is under-specification, not effective conciseness. It does not earn its place because it adds no information beyond the tool name. A concise description would still convey usage or context, but here every word is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description is severely incomplete. It does not mention that deletion is permanent, what happens if the ID is invalid, or any requirements like authentication or location context. The annotations help with destructiveness but the description fails to provide the operational context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation of the parameters. The 'id' parameter lacks a description in the schema (coverage is only 50%), and the description does not compensate by explaining that 'id' identifies the redirect to delete. The only parameter documentation is 'locationId' which is in the schema, not from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Delete' and the resource 'Redirect' by ID, which is clear and distinguishes it from siblings like funnels_update_redirect_by_id. However, it is essentially a restatement of the tool name with no additional specificity or context, so it barely meets the threshold of a specific verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that this is a permanent delete, when to prefer it over funnels_update_redirect_by_id, or any prerequisites. Agents are given zero context to decide between this and similar funnel tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no behavioral traits beyond the name. Despite annotations indicating readOnlyHint=false and openWorldHint=true, the description adds no context about side effects, permissions, or limitations. It does not contradict annotations, but it fails to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief but lacks meaningful content. It is under-specified rather than concisely informative, offering no structure or key details that aid an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, nested objects, multiple required fields), the description is severely inadequate. It does not explain what an estimate template is, the intended use case, or how it differs from related templates, leaving the agent with only the schema to infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high at 88%, and the schema includes informative descriptions for most parameters. The description itself provides no additional parameter semantics, but the baseline for high coverage is acceptable. No extra insight is offered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Estimate Template' essentially restates the tool name. It provides no additional elaboration on what creating an estimate template entails, making it a tautology rather than a clarifying statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like invoices_create_invoice_template or invoices_create_estimate. The description offers no context for selection or conditions of use.
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?
The description provides zero behavioral information beyond what annotations already declare (readOnlyHint=false implies a write operation). It does not disclose side effects, required permissions, error conditions, or any execution details. With annotations providing minimal context, the description adds no value for behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but under-specifies the tool. It lacks any structure such as key points, required fields, or examples. This is not thoughtful conciseness but rather an absence of information, making it inadequate for a tool with 25 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (25 parameters, 7 required, nested objects), the description is completely inadequate. It provides no context about required fields, how to structure items, or any high-level workflow. The schema has detailed descriptions, but the tool description itself fails to guide an agent on how to compose a valid request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 92%, meaning the input schema already documents nearly all parameters. The description offers no additional parameter meaning or examples, so it does not enhance understanding beyond the schema. Per the baseline rule for high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'New Estimate', but it is extremely generic and does not distinguish this tool from siblings such as invoices_create_estimate_template or invoices_create_invoice. It adds no detail about what an estimate is or how it differs from related invoice tools, so it meets only the basic clarity threshold.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever on when to use this tool versus alternatives like invoices_create_estimate_template or invoices_create_invoice. The description does not mention any prerequisites, context, or scenarios where this tool is the appropriate choice, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. However, the description adds no behavioral context beyond the name—no mention of what is returned, any authentication requirements, or implications of the altId/altType parameters. With annotations present, the burden is lower, but the description still contributes zero additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is brief, it is under-specified rather than appropriately concise. It consists of only two words, providing no useful structure or front-loaded information. A concise description should still convey essential purpose and usage; this one fails to do so, making it closer to under-specification than effective brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a retrieval tool with no output schema, so the description should explain what the tool returns (e.g., full invoice details) and any contextual requirements like location vs. company ID via altType. The description offers none of this, making it entirely inadequate for an agent to understand the tool's full capabilities and return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (invoiceId, altId, altType) are already documented in the schema. The description adds no extra meaning about parameter semantics—it does not clarify the relationship between altId and altType or the defaulting behavior that appears in the schema. Per the baseline rule for high coverage, a 3 is appropriate since the description does not need to compensate, but it also adds no value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get invoice' is essentially a tautology of the tool name 'invoices_get_invoice'. It states the verb and resource but adds no specificity about which invoice or any distinguishing features. While the name itself is clear, the description provides no incremental clarity and fails to differentiate from other invoice tools like get_invoice_schedule or list_invoices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. Among many invoice-related siblings (get_invoice_schedule, list_invoices, get_invoice_settings), the description provides no context for when this specific retrieval is appropriate or what it offers over others. This is a complete absence of usage guidance.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. However, it adds no behavioral context beyond that—no mention of return format, pagination, data scope, or any constraints. With annotations present, the bar is lower, but the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse—just 'List Estimates'—which is concise but under-specified. It lacks necessary details to be appropriately sized; while it has no wasted words, it also has no substance. The lack of structure makes it feel incomplete rather than efficiently minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, no output schema, and a two-word description, the tool is severely under-documented. The agent has no idea what the response looks like, how to interpret results, or how to set up pagination effectively. This is inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with each of the 9 parameters having a description in the schema. The tool description provides no additional meaning, so the baseline of 3 applies. It neither adds nor subtracts from the schema's documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'List' and the resource 'Estimates', which is clear but does not differentiate from siblings such as invoices_list_estimate_templates or invoices_list_invoices. The name itself carries the meaning, but the description adds no additional specificity or scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context about filtering or when not to use it. There is no mention of the tool's purpose in a broader workflow, leaving the agent without any decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds no behavioral context beyond that – it doesn't disclose side effects, what happens on success, or dependency on the locationId default. Given annotations exist, the bar is lower, but the description still fails to add any useful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short, but this is under-specification rather than conciseness. It has no structure or front-loaded essentials. Every word is minimal but fails to convey necessary information, so it is not effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 3 parameters, no output schema, and no explanation of the domain (e.g., what a 'link' is, what redirectTo means, how locationId defaults work), the description is far from complete. An agent cannot reliably call this tool without guessing at the semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 3 parameters, with only locationId having a description ('Defaults to GHL_LOCATION_ID when omitted'). The description 'Create Link' adds no meaning to name or redirectTo. With 33% schema coverage, the description should compensate, but it provides no parameter information at all, leaving the agent without any understanding of what these fields represent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Create' and the resource 'Link', so it's clear the tool creates a link. However, it's extremely terse and does not distinguish itself from sibling tools like links_update_link or links_delete_link. There is no elaboration on what a link is in this context or what 'create' entails beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus any alternative. There is no mention of context, prerequisites, or exclusions. It is purely the phrase 'Create Link' with zero usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry destructiveHint=true and idempotentHint=true, so the safety profile is known. However, the description adds no extra behavioral context—it does not state that deletion is permanent, irreversible, or whether it cascades to related data. It contributes nothing 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is minimal but is under-specification rather than appropriate conciseness. It simply repeats the tool name, so it does not earn its place by adding value. It is not verbose, but it is also not informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description does not explain what happens on success or failure, whether the task must exist, or any side effects. The agent must rely solely on the schema and annotations, which leaves critical gaps about the operation's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (id and locationId) documented in the schema: 'Recurring Task Id' and 'Location Id Defaults to GHL_LOCATION_ID when omitted.' The description adds no parameter information, so the baseline of 3 applies since the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Recurring Task' is a direct tautology of the tool name, restating the verb and resource without adding any new information about what a recurring task is, what deletion entails, or any nuance. It provides no distinction from other delete operations (e.g., locations_delete_custom_field).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like locations_update_recurring_task, locations_get_recurring_task_by_id, or locations_task_search. No prerequisites, intended use cases, or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds no behavioral detail. It doesn't explain side effects, required permissions, or what happens to the created folder. The description provides zero additional transparency 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is not conciseness; it's under-specification. There is no structure or front-loading of important information. The description fails to provide any useful detail and thus does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the description is drastically incomplete. It doesn't explain the purpose of the media folder, where it is created, any constraints, or what the return value might be. An agent cannot correctly infer when and how to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 4 parameters, so each is well-documented. The description adds no parameter-level context, but the schema already handles it. A baseline of 3 is appropriate since the schema covers the parameter semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Folder' essentially restates the tool name without adding specificity. It doesn't distinguish this tool from other folder-creation tools like custom_fields_create_custom_field_folder or clarify that this is a media-focused folder. The verb and resource are present, but the description is a tautology that provides no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, context, or exclusions. The description offers no information to help an agent decide when to invoke this tool instead of any other create tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and idempotentHint=false, implying a non-idempotent write operation, but the description adds no behavioral details. It does not disclose that each call creates a new record, potential side effects, or response behavior, so it adds no 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which is concise but fails to be informative. It is under-specified, providing no detail on resource type, behavior, or usage. While not verbose, it does not earn its place as it adds almost no value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters, a complex nested body, and no output schema, the description is completely inadequate. It provides no information on return values, error conditions, or operational context, leaving agents to guess how to construct valid calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented (schemaKey and body). The description itself adds no parameter-specific meaning, so the score is at the baseline of 3 for high coverage. However, the body parameter's description is vague ('Request body as defined by the HighLevel API') and the description does not compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Record' is a near-tautology of the tool name, providing only a verb and generic resource without specifying what kind of record or object it creates. It fails to distinguish from sibling tools like objects_create_custom_object_schema, as no scope or context is given.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or related tools (e.g., objects_get_record_by_id, objects_update_object_record), leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, which is consistent with the 'create' action, but the description adds no behavioral detail beyond that. It does not explain side effects (e.g., whether creating an integration overwrites or conflicts with existing ones), permission requirements, or any persistence implications. With annotations present, the bar is lower, yet the description still adds no value beyond restating the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief but not effectively structured. 'Create new integration' wastes the available space on a tautologous restatement of the tool name. While it is concise (no fluff), it fails to use the space to convey any differentiating or clarifying information, making it closer to under-specification than genuine conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 6 required parameters and no output schema, the description is grossly incomplete. It omits the payment integration domain, the purpose of the URLs, the meaning of the boolean flag, and any note about location defaults. An agent cannot understand what the tool does or what the consequences are without diving deep into the schema and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a meaningful description. The tool description itself contributes no additional semantic context—it does not clarify relationships between parameters (e.g., how paymentsUrl and queryUrl relate) or provide examples. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create new integration' states a verb and resource but is extremely generic. It does not specify that this is a payments integration, and the tool name alone carries the domain context. With multiple sibling tools named '*_create_integration' (e.g., ad_manager_fb_create_integration, ad_manager_google_create_integration), the description provides no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus the many alternative create_integration siblings. There is no mention of prerequisites, conditions, or exclusions. The agent must infer everything from the parameter schema and naming convention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds no additional behavioral context, such as pagination behavior, response format, or authentication requirements. With annotations covering safety, a score of 2 is appropriate because it still fails to disclose anything 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is not conciseness; it is under-specification. There is no front-loading of important details, no emphasis on key parameters or usage constraints. The description is minimized to the point of being unhelpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 13 parameters and no output schema, this tool is complex. The description offers nothing to help the agent understand the scope, semantics, or expected results. It is entirely inadequate for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of parameters, each with a description. The tool description does not add any extra meaning beyond the schema. Per the rubric, when schema coverage is high, a baseline of 3 is appropriate. The description does not compensate for any gaps because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Orders' states a verb and resource but is extremely generic. It does not distinguish this tool from other listing tools like payments_list_coupons or payments_list_transactions. It essentially repeats the tool name without any specifics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of the required altId parameter, the various filters, or any scenario that would make this the appropriate choice. No exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description gives no behavioral context beyond the verb 'update'. The schema reveals a destructive operation (`bulk-delete-products`) and various mutation types, but the description does not disclose this capability or any side effects, permissions, or reversibility. While annotations indicate non-read-only, the description adds no information about what can happen during execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase that offers no valuable information; it is under-specified rather than concise. For a tool with nested objects and multiple enums, it does not front-load critical operational details (e.g., required `type` and `productIds`) that an agent needs to safely invoke it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, nested objects, and a multi-option enum, the description is grossly incomplete. It fails to explain the filter mechanism, how the `type` selects the operation, or any return behavior. Combined with the lack of an output schema, an agent would have to fully parse the schema to understand usage, making this definition inadequate for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 10 parameters have descriptions in the schema (100% coverage), so the description's lack of parameter details is mitigated. The baseline of 3 applies because the schema already documents each parameter, and the description does not add any extra meaning about parameter relationships, defaults, or usage patterns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Bulk Update Products' is essentially a rephrasing of the tool name, offering no specificity about the types of bulk updates (price, availability, collection, delete, currency) that the schema's `type` enum lists. It lacks a clear verb-resource distinction and does not distinguish this tool from sibling tools like `products_bulk_edit` or `products_update_product_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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No conditions are provided (e.g., 'when updating multiple products at once' or 'when using filters instead of explicit product IDs'). The description is silent on selection criteria, leaving agents to guess based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds no behavioral details beyond the word 'Fetch', which is consistent with read-only. It does not disclose what the response contains (e.g., a single integer, a breakdown by rating) or any API constraints. The description is not contradictory, but it is redundant with the name and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence), but that brevity sacrifices clarity. It is not front-loaded with useful information; the phrase 'as per status' is misleading and unexplained. While concise in length, it is under-specified rather than appropriately sized, so structure fails to serve the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 optional parameters and no output schema, the description leaves the agent without essential context. It does not explain what 'status' refers to, what types of counts are returned (e.g., total count, count by rating), or how filters like storeId and productId combine. This is inadequate for a tool with this parameter richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—each parameter has a description. The tool description adds no additional meaning beyond what the schema already provides. Per the baseline for high schema coverage, a score of 3 is appropriate; the description does not enhance understanding of how parameters like altId, rating, or date filters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it fetches a review count, but the qualifier 'as per status' is ambiguous—there is no 'status' parameter in the schema. It essentially restates the operation implied by the name and provides no concrete clarification of what specific data is returned. It does not distinguish itself from sibling tools like products_get_product_reviews or products_get_product_store_stats beyond the word 'count'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that it is a read-only aggregation, when filtering by rating or date range is appropriate, or when a user should instead call a reviews list endpoint. The absence of any usage context leaves the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, meaning this is a write operation, and the description 'Attach' is consistent with that. However, the description adds no behavioral detail beyond the bare action—it does not mention what gets modified, whether the operation is reversible, what side effects occur, or what the response might contain. Since annotations carry the basic non-readonly signal, the description fails to enrich the behavioral model, leaving the agent without meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with no fluff—which is structurally efficient. However, it is too brief to provide any substantive value; it essentially restates the tool's name. While conciseness itself is not penalized, the lack of structure (no elaboration on parameters or behavior) makes the description under-specified, earning a mid-range score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 7 parameters, no output schema, and low schema coverage, the description is woefully incomplete. It does not explain input requirements, the nature of the 'attach' operation, or any expected outcome. An agent would have no idea that accountId and pageId are required, what they refer to, or what success looks like. The description offers almost no contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%, meaning 4 of 7 parameters (name, avatar, pageId, originId) lack any schema descriptions. The description does not provide any explanation of these parameters, their relationships, or how to populate them. For example, the required pageId is not described in the schema and the description does not hint at what it represents, leaving the agent to guess. With low coverage and no compensation, parameter semantics are critically underserved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Attach' and the resource 'Instagram Professional Accounts', which gives a basic sense of the action. However, it is vague about what 'attach' means in this context (e.g., linking an Instagram account to a page group) and does not differentiate from sibling tools like 'social_media_posting_attach_facebook_page_group' or 'social_media_posting_attach_linkedin_page_profile'. The name is more specific than the description, but the description lacks the detail needed to fully disambiguate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions that would make it the appropriate choice. It is a single sentence with no context about the workflow or when an agent should invoke this specific attach operation over other similar sibling tools. The absence of any usage direction makes it impossible for an agent to correctly reason about eligibility.
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?
The description adds no behavioral context beyond what annotations already declare (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false). It does not mention response format, whether shipping rates are included by default, or any side-effect-free nature beyond the annotations. The description is essentially empty of behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
It is concise (one sentence) but not effectively structured—it provides no front-loaded critical information. While brevity is positive, the content is so minimal that it fails to offer helpful guidance. A good concise description would still highlight key distinctions or required parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get-by-ID tool with siblings that list or fetch available zones, the description lacks context about its specific use case. It doesn't explain that it returns a single zone object, nor does it clarify the role of optional parameters like withShippingRate. The richness of the schema and annotations are not leveraged, leaving the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter (altId, altType, shippingZoneId, withShippingRate) has a clear description. The tool description adds nothing about parameters, but since the schema fully documents them, the baseline of 3 is appropriate—no extra compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Get Shipping Zone' is a clear verb+resource but is essentially a tautology of the tool name, adding no distinguishing details about whether it returns a single zone, multiple zones, or what filtering applies. It does not differentiate from siblings like store_list_shipping_zones or store_get_available_shipping_zones, so it fails to convey the specific retrieval-by-ID scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention that it fetches a specific zone by ID, nor does it reference sibling tools or any conditions (e.g., when to use list vs get). An agent would have to inspect the schema to infer its purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat these. However, it fails to add behavioral context such as the pagination behavior (limit/offset), the fact that it returns a list scoped to a shipping zone, or the default altId behavior. The description adds no 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse—just three words—but this is under-specification rather than effective conciseness. There is no structure, no front-loading of key information, and no attempt to convey tool behavior or requirements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (1 required), pagination controls, and no output schema, the description is severely incomplete. It doesn't mention the required shippingZoneId, the optional limit/offset, or what the returned data represents. An agent would have to open the schema and infer everything—this description provides negligible assistance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all five parameters, so the description is not responsible for documenting them. However, it also doesn't add any contextual meaning—it doesn't hint at the relationship between shippingZoneId and the list, or that altId defaults to location. Baseline 3 is appropriate because the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Shipping Rates' states a verb and resource, but it's essentially a rephrasing of the tool name and adds no scope or differentiation. It doesn't clarify how it differs from the sibling 'store_get_shipping_rates', and provides no information about what 'shipping rates' refers to in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like store_get_shipping_rates, store_list_shipping_zones, or store_create_shipping_rate. The description doesn't mention the required shippingZoneId parameter, read-only nature, or any conditions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the verb 'Get', which is consistent with the readOnlyHint annotation. No mention of pagination, filtering logic, default date ranges, or response format. While annotations cover safety, the description fails to disclose any operational behavior, so the burden is on 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but it is under-specified rather than concise. It conveys no useful structure or front-loaded information—just a noun phrase. It reads as a placeholder, not a crafted description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, this description is grossly incomplete. It fails to explain what is returned, how filters combine, or the pagination model. An agent would have to rely solely on parameter descriptions, which is risky for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (q, page, endAt, limit, startAt, surveyId, locationId) is already well-documented with meaning and defaults. The description adds no parameter-specific context, but given the full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Surveys Submissions' is essentially a restatement of the tool name. It states the verb and resource but adds no specificity about what 'submissions' means or how it differentiates from sibling tools like forms_get_forms_submissions. This is a tautology with minimal helpful distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No prerequisites, typical scenarios, or exclusions are mentioned. The agent receives no help in deciding between this and similar submission-fetching tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds no behavioral context beyond a bare verb. It does not mention return format, auth requirements, or any quirks, so it fails to add value beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely under-specified; it is a single phrase with no structure or elaboration. This is not concise, it is misleadingly minimal, similar to the 'Process' example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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 still fails to say what user data is returned, how the userId should be formatted, or any context that would help an agent decide if this tool is suitable. It is wholly inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents the single parameter userId with a description ('User Id') and 100% coverage, so the description is not required to explain the parameter. No additional semantics are provided, but the baseline is met.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get User' restates the tool name and title without adding any detail about scope, resource type, or how it differs from siblings like users_get_user_by_location or users_filter_users_by_email. It is essentially a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the numerous other user-fetching tools. There is no mention of alternatives, preconditions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, covering safety. However, the description adds no behavioral context beyond what annotations already convey—no mention of return format, errors, or any special conditions. It fails to leverage the opportunity to provide additional useful behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse ('Get Workflow') but this is under-specification rather than concise communication. It repeats the essence of the tool name without adding useful information. A succinct but informative description is expected; this lacks substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and only one optional parameter, so the description must carry the burden of explaining what the tool returns and how to identify a specific workflow. It does neither—there is no workflow ID parameter, leaving ambiguity about whether it retrieves a single workflow or all workflows. Essential context is missing entirely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter (locationId) is fully documented with a default behavior. The description adds nothing beyond the schema, so the baseline score of 3 is appropriate. No extra semantics are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Workflow' states a verb and resource but provides no distinguishing details. It doesn't clarify which workflow is retrieved or what identifies it, and it doesn't differentiate from any sibling tools. Compared to a tautology like 'Process', it is slightly better, but it remains too vague to be reliably selected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context, prerequisites, or exclusions are provided. The description gives no indication of scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare destructiveHint=true, which matches the 'Delete' action, so there is no contradiction. However, the description adds no context about what happens when a segment is deleted, whether deletion is reversible, required permissions, or side effects. With annotations already covering destructiveness, the description offers no additional behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), but it is under-specified and fails to provide useful context. It reads more like a placeholder than a helpful description, so it is not appropriately sized for an agent that needs to understand the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description gives no context about the segment types, the meaning of locationId, or any prerequisites. Given that this is a destructive operation and there are sibling tools for creating and retrieving segments, the description is inadequate to guide an agent on correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameters with descriptions, so the baseline is 3 even without parameter info in the tool description. The description itself does not mention parameters or add any meaning beyond what the schema already provides, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete segment' states a verb and resource, but it is essentially a restatement of the tool name. It does not specify that it operates on Google Ad Manager segments, nor does it distinguish between custom and data segments, which are the two enum options for the 'type' parameter. No additional specificity is provided beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like ad_manager_google_upsert_segment or ad_manager_google_get_segments. No conditions, prerequisites, or context for selecting segment type are provided. The description is completely silent on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds nothing beyond that—no mention of what data is returned, whether it supports pagination, or any side effects. For a read-only operation it is acceptable but lacks any additional behavioral context that annotations do not already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words, which is under-specification rather than conciseness. It fails to include any of the context an agent needs. The structure is not front-loaded; there is simply too little information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should clarify what the tool returns and how the parameters affect results. It does neither. It does not explain that 'type' is required or that 'id' is optional, nor does it note the default for locationId. The description is inadequate for a tool with 4 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are described in the schema (e.g., type is 'Asset type to retrieve'). The tool description itself adds no extra semantics about parameter interplay, defaults, or how to filter. This meets the baseline for high schema coverage but provides no bonus value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get assets' is a bare verb-noun phrase that adds almost no context. While the tool name hints at Google Ads, the description does not specify what kind of assets (e.g., text, image, call) or the scope (e.g., by advertiser or location). It barely distinguishes from other 'get' tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention conditions like 'use this when you need asset details by type' or contrast with ad_manager_google_upsert_assets or ad_manager_google_get_entity. An agent has no help deciding when this is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. However, the description adds no behavioral context beyond what annotations imply – it doesn't mention that it returns a list, whether location filtering is optional, or any side effects. Since annotations carry the safety profile, the description contributes nothing extra, warranting a below-average score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (3 words), but this is under-specification rather than effective conciseness. It lacks essential information and does not front-load any actionable detail. It parallels the 'Process' example in being too sparse to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With two required parameters and no output schema, the description should explain what the tool returns and how parameters influence the result. It doesn't. It also fails to clarify the meaning of 'target interests' in the Google Ads context. Given the complexity of ad targeting, this description is inadequate for an agent to call it correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – each parameter (type, locationId, advertisingChannelType) has a basic description. The tool description adds nothing about parameters. Baseline for high coverage is 3, and the description does not improve on it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get target interests' restates the tool name almost exactly, providing no additional specifics. It does identify the verb (get) and resource (target interests), but gives no detail on what constitutes a target interest, its scope, or how it differs from sibling tools like ad_manager_google_get_audiences or ad_manager_google_search_targeting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or typical use cases. An agent reading this alone would have no idea when to select it over the many other ad_manager_google_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds no behavioral context beyond the safe operation claim. It does not mention that it returns a list, any pagination, or what data is included. While it does not contradict annotations, it adds no value beyond what structured data already conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Being a single phrase is concise, but it is under-specified rather than efficiently packed. It omits essential details like scope and return behavior, making it closer to an incomplete stub than a concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list-retrieval tool with no output schema, the description should explain that it returns all lead forms for an account, possibly noting the locationId default. It does none of this. The description is inadequate for an agent to understand what data to expect or how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; both parameters have descriptions (accountId as 'Account identifier' and locationId with default behavior explained). The description adds no additional parameter meaning, but since the schema is thorough, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get lead forms' states a verb and resource, but is vague. It does not specify which lead forms (LinkedIn vs Facebook) or any filtering/scoping, and does not differentiate from sibling tools like ad_manager_fb_get_lead_form or ad_manager_fb_get_page_lead_forms. It is nearly a restatement of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There are many sibling tools for retrieving lead forms (e.g., ad_manager_fb_get_lead_form, ad_manager_li_create_lead_form), but the description gives no context, exclusions, or alternative names. An agent would have to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. However, the description adds no behavioral context beyond those flags – it does not mention what the returned list contains, whether pagination is involved, or any special constraints (e.g., date range limits). With annotations covering the safety profile, a 2 reflects the lack of any additional behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It conveys only a vague intent and does not front-load any useful constraints or clarifications. While there is no wasted text, the structure fails to provide the agent with decision-relevant information. A concise description should still be informative; this one is just terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, 5 required, and no output schema, the description must clarify what the tool returns and how to interpret the parameters. It does neither. The description is insufficient for an agent to know what a 'reporting list' is or how to differentiate it from other reporting endpoints. The presence of sibling tools that are similarly named makes the lack of context especially problematic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter has a description (e.g., 'Start date in yyyy-mm-dd format', 'Campaign ID'). The tool description itself adds no parameter guidance – it does not explain how parameters relate to each other or what 'fields' list implies. Since the schema already documents the parameters well, the description does not need to repeat that, and a baseline 3 is appropriate. It could improve by clarifying the 'listType' parameter, which is simply 'List type' and offers no examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get reporting list' states a verb and a noun, but 'reporting list' is ambiguous – it does not specify what kind of list (e.g., list of reports, list of metrics, list of campaigns) or for which ad platform (LinkedIn is implied by the name but not in the description). It does not distinguish this tool from siblings like ad_manager_li_get_campaign_group_reporting or ad_manager_li_get_ad_analytics, which also deal with reporting. The resource is too vague to be actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus its many siblings. No mention of context, prerequisites, or conditions that would make this tool the right choice. For example, it does not say 'Use this for a list of report entries, while ad_manager_li_get_campaign_group_reporting returns aggregate campaign stats.' The absence of any usage guidance is a critical gap given the large number of similar ad_manager tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context, such as pagination behavior, return format, or filtering semantics. It neither contradicts nor enriches 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but under-specified. It provides no useful information beyond the tool name, making it under-specification rather than effective conciseness. Every word is wasted on repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and a description that only says 'List Affiliates', the tool is severely incomplete. It doesn't mention filtering capabilities, pagination, or any constraints, which is inadequate for an agent to select and invoke it correctly in a large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only limit and locationId have descriptions). The description provides no information about any of the 8 parameters, including query, active, date ranges, campaignId, skip, etc. It fails to compensate for the low schema coverage, leaving most parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Affiliates' states the verb and resource, distinguishing it from singular get_affiliate and other list tools. However, it is extremely minimal, essentially repeating the tool name, and gives no scope or filtering context. It is clear but not specific about what is listed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like affiliate_manager_get_affiliate, affiliate_manager_list_commissions, or affiliate_manager_list_payouts. No prerequisites or conditions are mentioned, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the deprecation note, which is a behavioral trait, but it provides no other behavioral context such as return format, authentication requirements, or any side effects. With annotations covering safety, the bar is lower, but the description still offers minimal additional transparency beyond the deprecation status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which could be seen as concise in length, but it is under-specified rather than efficiently structured. It provides no elaboration that would help an agent use the tool. The single phrase could have been expanded with useful details without becoming verbose, so it fails to make every sentence earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and is deprecated with a sibling non-deprecated version, the description is grossly incomplete. It says nothing about what the tool returns, when to use it, or how it relates to alternatives. An agent is left without essential guidance for correct invocation, making this definition inadequate even for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions no parameters at all. Schema coverage is only 33%, with only locationId having a description ('Defaults to GHL_LOCATION_ID when omitted.'), while agentId (the required parameter) and source have no descriptions. The description does nothing to compensate for this low coverage, leaving the required parameter completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get Agent (Deprecated)' which conveys the basic action and resource, but it's minimal and does not go beyond the tool name. It does not specify that it retrieves by ID beyond the name itself, and it does not differentiate from the sibling 'agent_studio_get_agent_by_id' which appears to be the non-deprecated version. The description essentially restates the name with a deprecation tag, lacking specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage hint is 'Deprecated', which implies it should be avoided, but it does not name the preferred alternative or provide any condition for when to use this tool versus the non-deprecated sibling. No explicit guidance is given on selection between this and 'agent_studio_get_agent_by_id' or when this might still be appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. However, the description adds no behavioral context beyond that, such as the fact that results are paginated via limit/offset, that a default location applies, or that the response is a list. It is a bare statement that provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only four words, which is extremely concise but not appropriately sized. It omits critical context (e.g., what is being listed, scoping) and does not front-load the key distinction. While it has no waste, it is under-specified to the point of being unhelpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and only terse annotations, the description should explain that this retrieves a paginated list of blog authors for a location, possibly with default behavior. It lacks this context, making it incomplete for an agent to understand what the tool does beyond the name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (limit, offset, locationId) already has a clear description in the schema. The description adds no additional semantic meaning about parameters. Per the rubric, baseline is 3 when coverage is high, so this score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all authors' is vague and underspecified. It does not indicate that these are blog authors, nor that the results are scoped by location. The tool name carries the specificity, but the description itself could apply to any author entity. It is nearly a tautology of the name and fails to differentiate from siblings like blogs_get_all_categories_by_location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention pagination, default location behavior, or when this tool is preferred over other blog-related or author-related tools. An agent receives no context about typical usage scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, but the description adds no additional context. It does not mention that results are paginated via limit/offset, nor that locationId defaults to GHL_LOCATION_ID when omitted. It adds nothing beyond what is structurally available.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The phrase 'Get all categories' is extremely brief, but it is not concise in a meaningful way—it lacks substance and does not earn its place. It is an under-specified statement rather than an efficient description, and it provides no front-loaded scoping information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's purpose, the description is incomplete. It does not state that it returns blog categories for a location, nor does it clarify the output format. With no output schema and only a minimal input schema, the description needs to provide at least basic context about what is returned, which it fails to do.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even with no parameter info in the description. The description does not add any extra meaning to parameters; it simply repeats the generic action. No improvement or degradation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description merely states 'Get all categories' without specifying that these are blog categories or that they are scoped to a location. This is vague and fails to distinguish the tool from siblings like blogs_get_all_blog_authors_by_location or social_media_posting_get_categories_location_id, which also fetch categories by location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description does not mention any context such as filtering by location, pagination, or when one might choose this over similar category-related tools. There is no comparison or exclusionary language.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat that. However, the description adds no behavioral context – it does not state what is returned, whether additional data is included, or any edge cases. Given the annotations, a description could add value by explaining the retrieval scope, but this one is purely generic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse ('Get Brand Board') but this is under-specification, not conciseness. It omits critical context (like the ID requirement) and does not provide enough information to be called concise in a meaningful way. It is a single phrase with no elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters and full schema coverage, the tool is not complex, but the description still fails to explain the key differentiator (retrieval by ID) or any practical context. An agent would need to rely on the name and schema to understand what makes this tool unique, which is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – both `id` and `locationId` have descriptive text. The description offers no additional meaning about the parameters, so the baseline of 3 applies because the schema already handles parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Get Brand Board' which names a verb and resource, but it does not specify that this retrieves a single brand board by its ID. This makes it indistinguishable from sibling tools like brand_boards_get_brand_boards_by_location, which also get brand boards. The name contains 'by_id', but the description does not reinforce that nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the location-based retrieval. No mention of the required `id` parameter or any context about scenarios where this is appropriate. An agent is left to infer usage solely from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint: true, readOnlyHint: false, idempotentHint: true, and openWorldHint: true, so the description does not need to restate these. However, the description adds no additional behavioral context, such as what happens to associated calendars, events, or schedules when a group is deleted, or whether the operation is reversible. It fails to enrich the annotation information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short with no wasted words, it is under-specified rather than appropriately concise. It lacks structure or any elaboration that would aid an agent. The brevity is a symptom of incompleteness, not disciplined conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a destructive operation with no output schema, the description should explain what a group is, the consequences of deletion, and any relevant context. The current description is inadequate for an agent to understand the operation's scope and implications, even though the parameter is simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single required parameter groupId, which already includes a description 'Group Id'. The tool description adds nothing beyond this, but because the schema fully documents the parameter, the baseline score of 3 applies. There is no additional meaning or context provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Group' is a near-tautology of the tool name 'calendars_delete_group'. It identifies the verb and resource but provides no context about what a 'group' is in the calendar domain or what deleting it entails. It does not distinguish this from sibling delete operations like calendars_delete_calendar or calendars_delete_schedule, which could be easily confused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, what prerequisites exist, or how it differs from alternatives. An agent cannot determine whether deleting a group is appropriate for a given task or whether a different calendar operation should be chosen. No exclusions, context, or alternative routing is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, the description adds no extra behavioral context such as pagination behavior, ordering, or that it returns a list of resources. It merely restates the function name without providing details that would help an agent understand what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (four words), which is front-loaded but at the cost of content. It is under-specification rather than appropriate conciseness. A single phrase cannot convey necessary usage details, making it poorly structured for an operational tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters (3 required), no output schema, and a sparse description, the context is grossly incomplete. The agent lacks information about parameter semantics, return format, pagination, and any filtering options. This is insufficient for correct invocation, even with annotations covering safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with resourceType and locationId having descriptions, but limit and skip lack them. The description adds no further information about any parameter, failing to compensate for the missing schema documentation. An agent would not know the meaning of limit or skip, or what values resourceType can take beyond the enum, without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (List) and a specific resource (Calendar Resources), which conveys the basic operation. However, it does not differentiate from siblings like calendars_get_calendar or calendars_get_calendar_resource, and it lacks detail about the scope (e.g., which types of resources). It is adequate but not specific enough to fully distinguish this tool from related ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of filtering, pagination, or prerequisites. The description is a single phrase and offers no contextual advice for invoking the tool correctly. An agent would have no idea which scenarios call for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already communicate the safety profile. The description adds no behavioral context beyond that—it does not mention filtering, pagination, or what the response contains. It does not contradict the annotations, but it also contributes nothing new.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—just two words—but this is under-specification rather than conciseness. It lacks any structure that would help an agent understand the tool's scope, return value, or filtering behavior. Every sentence should earn its place; here there is not even a full sentence of useful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three optional parameters and no output schema, the description should explain what the tool returns (e.g., a list of calendars) and any side effects (though readOnly is implied by annotations). The description does not convey the operation's purpose beyond the generic name, leaving the agent to rely entirely on the schema and annotations, which are insufficient for understanding the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters (groupId, locationId, showDrafted) with descriptions, and schema description coverage is 100%. The tool description provides no additional parameter guidance, so the baseline of 3 applies as the schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description "Get Calendars" is essentially a restatement of the tool name 'calendars_get_calendars' and adds no additional specificity. It does not indicate whether this lists all calendars, supports filters, or differs from sibling tools like calendars_get_calendar or calendars_get_groups. While it has a verb and resource, it lacks any distinguishing detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternative calendar-related tools. With dozens of sibling tools such as calendars_get_calendar, calendars_get_calendar_events, and calendars_get_schedule_by_id, the description gives an agent no indication of which operation is appropriate for a given context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and idempotentHint=true, but the description adds no behavioral context such as consequences of removal, whether the schedule remains intact, or any prerequisites. The description provides no value beyond the annotations and even introduces directional confusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is short, it fails to accurately convey the operation's direction, making it not worth the words. The sentence is misleading rather than helpful, so it does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool requires two IDs and has no output schema; the description does not explain what happens after removal, whether the operation is idempotent (though annotation says so), or any side effects. It is insufficient for an agent to confidently invoke, lacking critical context about the operation's semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both id and calendarId are well-documented in the schema. The description does not add any additional meaning or clarify the relationship between the parameters, so a baseline score of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Remove user availability schedule from a calendar', but the tool name indicates the inverse operation: removing a calendar from a schedule. This direction mismatch makes the purpose ambiguous and potentially misleading for an agent. It does specify a clear verb and resources but incorrectly reverses the relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as calendars_add_calendar_to_schedule or calendars_delete_schedule. The description does not mention that it is the inverse of adding a calendar to a schedule, nor does it provide any context about intended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds no behavioral context beyond what annotations already imply. It does not state what the update does, whether it overwrites the entire note body, or any side effects. It neither contradicts annotations nor provides meaningful extra information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is severely under-specified rather than concise. It lacks any structure, front-loading, or explanatory value. Every word is wasted because it adds nothing beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters and no output schema, the description is highly incomplete. It does not mention that it updates the body of a note associated with an appointment, nor does it explain the relationship between appointmentId, noteId, and body. The description provides nearly no contextual information needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (three of four parameters have descriptions). The description does not illuminate any parameter meaning; it only says 'Update Note'. For the undocumented 'userId' parameter, no clarification is given, and the description does not compensate for the moderate coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Note' is essentially a tautology of the tool name, restating the verb and noun without specifying that this is about appointment notes. It fails to distinguish this tool from other note-update tools (e.g., contacts_update_note) and provides no context about the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, typical scenarios, or exclusions. An agent cannot determine when this should be selected over similar calendar note tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not mention idempotency, side effects, permissions, or partial-update semantics, and it doesn't clarify what 'update' entails. While it doesn't contradict annotations (readOnlyHint=false, idempotentHint=true), it is entirely uninformative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but it is under-specified rather than concise. It provides no meaningful content, leaving the agent without necessary context. While it is short, it doesn't earn its place as it delivers no information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, an enum, and no output schema, the description is grossly incomplete. It offers no overview of what the update operation does, the types of resources (rooms/equipments), or any required versus optional fields. An agent cannot reliably determine how to construct a valid request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description says nothing about any parameters. The schema covers 70% of parameters (7 of 10) with descriptions, but the remaining 30% (name, isActive, description) lack schema docs and are not addressed in the tool description. The description adds no value beyond what the schema already provides, and it fails to compensate for the uncovered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Calendar Resource' simply restates the tool name without adding any specifics about what resources are, what attributes can be updated, or how it differs from sibling tools like calendars_create_calendar_resource or calendars_delete_calendar_resource. It is a tautology of the name, providing no additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, required fields, or conditions under which an update is appropriate. An agent has no context for when to choose this over create/delete operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is clear. However, the description adds no additional behavioral context such as what side effects might occur, whether the task is linked to a contact automatically, or any permissions required. It does not contradict annotations, but it adds zero value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely concise (one short sentence), this is under-specification rather than effective conciseness. There is no structure or informative content. The description does not earn its place; it is merely a placeholder that repeats the concept in the name without adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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, and low schema coverage, the description is severely incomplete. It does not explain the purpose in the context of contacts, does not describe return values (since there is no output schema), and provides no detail about how to construct a valid request. An agent has almost no information to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only contactId has a description 'Contact Id'), leaving 5 of 6 parameters undocumented. The description 'Create Task' provides no information about what the parameters mean, how they relate, or which are required beyond the schema itself. With low coverage, the description must compensate, and it completely fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Create' and resource 'Task', which is clear at a basic level, but it does not specify that the task is associated with a contact (despite the tool name 'contacts_create_task') and does not distinguish it from other create tools like 'contacts_create_note' or sibling tools across different domains. It is not a tautology, but it offers no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description simply says 'Create Task' with no mention of context, prerequisites, or exclusions. An agent has no signal about whether to use this or e.g. 'contacts_update_task' or 'locations_create_recurring_task'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. However, the description adds no additional context, such as the irreversibility of the deletion, whether it permanently removes configurations, or any safety warnings. With no extra disclosure beyond the annotations, it fails to provide meaningful behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is technically concise, but it is under-specified rather than efficiently informative. Two words ('Delete Agent') add almost no value beyond the tool name and fail to earn their place. There is no structure or front-loading of critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one required parameter, the description is still inadequate. It does not clarify the scope of deletion (e.g., is it permanent? does it cascade to related resources?), nor does it mention any return values or success criteria. The agent has to infer behavior solely from the name and annotations, which is insufficient for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter 'agentId' is fully documented with the description 'Conversations AI agent id'. The tool description adds nothing beyond the schema, but since the schema is already explicit, this meets the baseline for a single-parameter tool. No additional semantic value is required from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Agent' states a verb and resource, but it is extremely generic. It does not specify that this is for Conversation AI agents, and there are sibling tools like agent_studio_delete_agent and voice_ai_delete_agent that delete different types of agents. Without context, an agent cannot clearly distinguish this tool from related ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives such as conversation_ai_update_agent or agent_studio_delete_agent, nor does it mention any prerequisites or side effects. The agent is left with no basis for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is covered. However, the description adds nothing beyond the annotations—no mention of the return payload, pagination, or any side effects. Since annotations carry the burden, the description's lack of added context results in a low score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than concise efficiency. It contains no useful information beyond the tool name, so it does not earn its place. The structure is minimal but lacks the substance needed to guide an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool without an output schema, the description should at least mention that it returns agent details or how the result is shaped. No such information is present. The presence of siblings like conversation_ai_search_agent and conversation_ai_get_action_by_id creates a need for differentiation that is unmet. The description is incomplete for helping an agent call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the single parameter agentId is documented as 'Conversations AI agent id'. This satisfies the baseline. The description does not elaborate further on the parameter, but the schema provides adequate meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Agent' essentially restates the tool name without adding any specific context about what the agent is or what fields it will return. It fails to distinguish this from siblings like conversation_ai_get_action_by_id or conversation_ai_search_agent. The verb and resource are clear but the description is tautological and does not explain the scope or nature of the retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of when to prefer get_agent over search_agent, how to obtain agentId, or any prerequisites. The description gives the agent no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and idempotency. However, the description adds no behavioral context beyond that—it doesn't mention return format, whether the full conversation object is returned, or any constraints. Given the annotation coverage, the bar is lower, but the description still fails to provide meaningful behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase, 'Get Conversation', which is extremely sparse. While it is concise, it is under-specified and lacks any structure or useful information. The string is essentially the tool name with no added value, making it more of a placeholder than a structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get-by-ID tool with a clear sibling (conversations_search_conversation) and no output schema, the description should clarify what a conversation is, what is returned, and when to use this as opposed to searching. The current description provides none of this context, leaving the agent to infer everything from the parameter name and tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter conversationId, with a clear schema description 'Conversation ID as string'. The tool description adds nothing beyond the schema, which is acceptable per the baseline for high coverage, but it also does not contribute any additional semantic clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Conversation' simply restates the tool name without adding any specificity. It doesn't indicate what a conversation is, what data is returned, or how it differs from sibling tools like conversations_search_conversation or conversations_get_messages. This is nearly a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description offers no guidance on when to use this tool versus alternatives such as conversations_search_conversation or conversations_get_messages. An agent has no indication of prerequisites, use cases, or why to pick this over similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds no additional behavioral context, such as whether it creates a conversation, updates status, or supports scheduling. It does not contradict annotations but also does not supplement them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (four words) but lacks structure and front-loaded information. While it avoids verbosity, it is a single vague phrase that does not convey the tool's scope or complexity. Conciseness without substance earns an average score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 25 parameters, 4 required, nested objects (e.g., forwarding, scheduling), and no output schema, the description is grossly inadequate. It provides no explanation of required fields, channel-specific behavior, or response expectations, making it far from complete for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter has a description in the schema. The tool description does not mention any parameters or add meaning beyond what the schema already provides. This matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a new message' is generic and essentially restates the tool name without adding specificity. It does not clarify that this operates within a conversation or distinguish it from sibling tools like conversations_add_an_outbound_message or conversations_add_an_inbound_message, which also send messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no mention of channel types, no prerequisites, and no exclusion cases. An agent cannot determine if this is appropriate for a given scenario compared to other message-sending tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context, such as whether the response is a list, requires specific authentication, or involves pagination. For a read operation, the description should at least hint at the return scope, but it is silent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but that brevity is not effective conciseness—it omits essential context. It is a single phrase that restates the tool name, carrying minimal informative value. The structure is acceptable (one line), but it does not earn its place as a useful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with two parameters and no output schema, the description should explain what the tool returns and when it is appropriate to use. It does neither. While annotations cover the safety profile, the description leaves the agent without understanding the data returned or how this tool fits into custom fields workflows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema, including the objectKey prefix requirement and the locationId default. The description adds no parameter information beyond the schema, so it performs at the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Custom Fields By Object Key' is essentially a restatement of the tool's name. It clarifies the verb and resource but adds no detail about what custom fields are, what an object key represents, or what the tool returns. It fails to distinguish this tool from siblings like custom_fields_get_custom_field_by_id, which also retrieves custom fields but 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of use cases, prerequisites, or differences from sibling tools. An agent cannot determine whether to choose this or custom_fields_get_custom_field_by_id without opening schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation), destructiveHint=false, and idempotentHint=false, but the description adds no behavioral context beyond what the annotations already imply. It does not disclose side effects such as marking the estimate as invoiced (even though the markAsInvoiced parameter suggests this), nor any prerequisites like the estimate needing to exist. No contradiction with annotations, but the description is silent on behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one short phrase, which is concise but under-specified. It fails to front-load any useful details like intended use, prerequisites, or side effects. While there is no fluff, the brevity significantly reduces its usefulness; it is not informative enough to guide an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that converts an estimate into an invoice, the description lacks critical context: what happens to the original estimate (e.g., is it automatically marked as invoiced?), requirements like the estimate existing, and any return value (no output schema is provided). The absence of these details makes the tool incomplete for correct invocation, even though the parameter list gives some hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so all parameters (estimateId, markAsInvoiced, altId, altType, version) are documented in the schema. The description adds no additional meaning about how these parameters relate to the operation. Per the rubric, baseline is 3 when schema coverage is high, and the description does not compensate or add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description "Create Invoice from Estimate" essentially restates the tool name (invoices_create_invoice_from_estimate) with slight rephrasing. It identifies the verb and resource but adds no detail that distinguishes it from other invoice tools like invoices_create_invoice or invoices_record_invoice. It is not a pure tautology, but it provides no extra clarity about the conversion process or conditions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides zero guidance on when to use this tool versus alternatives. It does not mention that it requires an existing estimate, how it interacts with the estimate's status (despite the markAsInvoiced parameter), or when to prefer this over other invoice creation methods. No exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description does not need to repeat that. However, the description adds no behavioral context—no mention of what is returned, whether it uses existing sequences, or any side effects. With annotations present, a score of 2 reflects that the description is minimal and uninformative but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but this is under-specification rather than conciseness. It omits critical information that an agent needs, making it ineffective despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the tool returns—such as a string containing the estimate number—but it does not. It also fails to clarify how the generation works or any constraints. For a tool that generates a number, the absence of return-type information is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both altId and altType documented in the input schema. The description does not add any additional meaning about how these parameters affect the generated number, but the baseline of 3 is appropriate since the schema already covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Generate Estimate Number' is essentially a restatement of the tool name. It lacks specificity about what an estimate number is, how it is generated, or what makes it distinct from similar tools like invoices_generate_invoice_number. An agent would need to guess 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Despite the presence of invoices_generate_invoice_number and other invoice-related tools in the sibling list, there is no mention of use cases, prerequisites, or when to prefer this tool. The agent is left entirely to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no further behavioral context—no mention of what the schedule contains, whether it returns the full schedule, or any edge cases. It merely restates the action without enriching the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than effective conciseness. It is not front-loaded with useful information; it simply paraphrases the tool name. The single phrase offers no structural benefit and could mislead due to grammatical issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get operation with only three parameters and no output schema, the description still fails to provide basic context. It does not explain what an invoice schedule is, how it relates to invoices, or what the response format might be. An agent would have to rely on external knowledge or guess. The description is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (scheduleId, altId, altType), so schema coverage is 100%. Per baseline, a score of 3 is appropriate since the schema carries the semantic weight. The description adds nothing beyond the schema, so it neither helps nor hurts beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get an schedule' is a near-tautology of the tool name 'invoices_get_invoice_schedule'. It provides no additional specificity about what an invoice schedule is or what this operation does beyond the verb and resource already visible in the name. The grammar error ('an schedule') further reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many sibling tools (e.g., invoices_list_invoice_schedules, invoices_update_invoice_schedule, invoices_cancel_invoice_schedule). No mention of prerequisites, alternatives, or exclusion criteria. The description is entirely silent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond that, such as return format, pagination, or what 'links' refers to. Given the annotations provide the safety profile, the description contributes minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but it is not meaningfully concise—it is a tautology. It does not front-load any actionable detail; it simply restates the tool name. The single sentence fails to earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should clarify what is returned, but it does not. It lacks any context about the result set, filtering, or how the locationId affects the response. The presence of annotations covers safety but not functional completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter locationId is fully documented in the schema with a default note. Since schema description coverage is 100%, the baseline is 3. The description adds nothing about parameter semantics, so it remains at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Links' merely restates the tool name. It does not specify what kind of links, what is returned, or how it differs from sibling tools like links_get_link_by_id or links_search_trigger_links. The purpose is vague and lacks a clear 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No information is provided about when to use this tool versus its siblings. There is no mention of alternative tools, filters, or scenarios. An agent has no guidance to select this over the many other link-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnlyHint false) and non-idempotent. The description adds nothing about behaviors such as whether the first task is created immediately, permission requirements, or error handling. It contributes no extra behavioral information beyond what the annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is a single sentence, it is under-specified rather than concise. It lacks structure and front-loading of critical information, leaving the agent with no useful insights beyond the name. It is too sparse to be considered efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested rruleOptions with required sub-fields, 7 parameters, and many related sibling tools), the description is grossly incomplete. It does not mention required fields, clarify recurrence syntax, or describe the response. The schema covers parameters but the description fails to provide any higher-level context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all 7 parameters, including nested rruleOptions sub-fields (100% coverage). Since the description adds no additional meaning beyond the schema, it meets the baseline for high schema coverage without enhancing understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Recurring Task' essentially restates the tool name. It identifies the verb and resource but offers no elaboration on what a recurring task is or how it differs from similar create operations (e.g., contacts_create_task). It provides minimal added clarity beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides zero guidance on when to use this tool versus alternatives like contacts_create_task or locations_update_recurring_task. There is no mention of scenarios, prerequisites, or comparison with sibling tools, leaving an agent without any routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as readOnly, idempotent, and non-destructive, so the safety profile is covered. However, the description adds no additional behavioral context, such as whether the result is a list, whether there is pagination, or what the response shape is. Since no extra info is provided beyond the annotations, the description does not fulfill its burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is under-specified rather than concise. It lacks the necessary context to be useful, which goes beyond conciseness into inadequacy. The minimal text does not front-load useful information; it simply states the obvious action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 should clarify what the tool returns, but it does not. With a single optional parameter and no return type information, the agent is left without enough context to understand the result. The description is far from complete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the only parameter, locationId, is fully documented in the schema itself ('Location Id Defaults to GHL_LOCATION_ID when omitted'), providing 100% coverage. The description 'Get Tags' adds no further semantic meaning, but given the high schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Tags' is a bare verb-object phrase that omits the context of tags (location tags) and the resource scope. It does not differentiate this tool from siblings like 'locations_get_tag_by_id' or 'social_media_posting_get_tags_location_id', both of which are also about tags. It is slightly better than a tautology because it states an action, but it lacks the specificity required to be unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention that this returns all tags for a location, nor does it contrast with 'locations_get_tag_by_id' for fetching a single tag. An agent has no indication of the appropriate context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds no additional behavioral context, such as what happens if the custom value does not exist, authorization requirements, or side effects. It merely restates the action without any enrichment 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise in length, but it is under-specified and reads almost like a tautology of the tool name. It does not front-load any useful information; every word is essentially redundant with the name. It is not appropriately sized because it fails to convey any operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with four parameters and no output schema, this description is completely inadequate. It does not explain what a custom value is, how 'id' relates to it, what 'name' and 'value' represent, or any constraints. An agent cannot infer how to call this tool correctly from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. The input schema provides descriptions for 'id' and 'locationId', but 'name' and 'value' are undocumented. With 50% schema coverage, the description should compensate for the missing parameter meanings, but it does not. This leaves two critical parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('Custom Value'), so it is not a pure tautology. However, it does not clarify what a custom value is or how it relates to locations, and it does not distinguish this tool from siblings like locations_create_custom_value or locations_get_custom_value. The purpose is clear at a high level but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as locations_create_custom_value or locations_get_custom_value. There is no mention of prerequisites, use cases, or conditions that would make this the preferred choice. No usage context is given at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and destructiveHint=false, so the agent knows updates are non-destructive and repeat-safe. However, the description itself provides no behavioral context—e.g., whether fields are merged or replaced, whether optional fields clear existing values, or any side effects. Given annotations cover some safety profile, the description adds negligible value here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), but this is under-specification rather than effective brevity. It fails to convey any useful context or structure. A concise description should still front-load key information; this one provides none.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with 8 parameters, a nested recurrence object, and no output schema. The description provides no information about the update semantics, return value, or how recurring rules interact. Given the complexity, the description is severely incomplete and does not help an agent correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a descriptive label. The description adds no extra meaning beyond what the schema already provides, so it stays at the baseline 3. The nested rruleOptions object has required subfields, but the description doesn't explain how to use them; that's left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Recurring Task' is a near-verbatim restatement of the tool name, adding no new information about the verb or resource. It doesn't clarify what 'update' entails or distinguish this from sibling tools like locations_create_recurring_task or locations_delete_recurring_task. An agent gains no additional insight beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, such as needing an existing recurring task ID, or when to prefer update over create/delete. The description is entirely silent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description does not need to restate those. However, it adds no behavioral context beyond the verb 'update' – nothing about partial vs full updates, effects on existing tags, or response format. With annotations covering basic safety, the description still offers minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Update tag'), which is concise but not informative. It lacks structure and front-loading of key details. This is under-specification rather than effective conciseness – the one-word verb provides no useful guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no additional prose, the description is grossly incomplete. An agent would need to infer the tool's behavior, prerequisites, and side effects. The schema covers parameter names and defaults, but the overall context of the update operation (e.g., whether it renames the tag, partial updates, error conditions) is entirely absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – all three parameters (name, tagId, locationId) have explicit descriptions. The description adds nothing about parameters, but because the schema fully explains them, the baseline score of 3 is appropriate. No compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is 'Update tag' – it states a verb and a resource but lacks any specificity. It does not clarify that this updates a tag in the Locations context, nor which properties can be changed, and it does not distinguish it from sibling operations like create, delete, or get tag. It is more than a pure tautology but only minimally 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that this modifies an existing tag's name, nor does it reference related tools such as locations_create_tag or locations_delete_tag. The agent receives no context to decide between similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. However, the description adds no behavioral context beyond the name—no mention of return format, error handling, or side effects. It contributes nothing beyond the annotations, which is a weak score given the description's responsibility to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Get Record By Id'), which is concise but under-specified. It lacks any structural elements such as context or guidance, and it is not front-loaded with useful information. It is more of a tautology than a concise explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool, the description is insufficient. It does not explain what the tool returns (no output schema), how to identify a record, or any limitations. An agent would struggle to understand the scope and purpose beyond the name and schema. Given the lack of output schema and the minimal description, the tool is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptive parameter descriptions for both id and schemaKey. The tool description adds no parameter-level meaning, but the schema adequately explains the parameters, including the custom_objects. prefix requirement. Since the schema does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Record By Id' restates the tool name with little added specificity. While it does name a verb and resource, it does not clarify what kind of record this refers to (e.g., custom object vs standard object), leaving the meaning ambiguous. Compared to siblings like objects_get_object_by_location_id, it is not differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention when to prefer it over objects_search_object_records or other get-by-id tools, nor does it explain any preconditions. The description provides zero usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description doesn't contradict them. However, it adds no behavioral context beyond that—no mention of side effects, permission requirements, or what happens to existing data. It relies entirely on annotations with zero additional disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. It provides no value beyond the tool name and fails to front-load any actionable information. Every word is wasted because it doesn't communicate anything new.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the schema covering parameter details, the description is too sparse to support correct use. It doesn't explain what a 'record' is, how to identify it, or the implications of the update. An agent would have to infer context from the schema and annotations alone, which is insufficient for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (id, body, schemaKey, locationId) is fully documented in the schema itself. The description adds no parameter-level meaning, but under the baseline rule for high coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Record' is a tautology that essentially restates the tool name. It fails to clarify what type of record, whether it's for custom or standard objects, or the scope of the update. The verb is present but the resource is ambiguous, and it doesn't distinguish from sibling tools like objects_create_object_record or objects_delete_object_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance whatsoever on when to use this tool versus alternatives. The description does not mention prerequisites, related tools, or any conditions that should trigger selection. With many sibling tools covering object record operations, this absence is critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context—no note on return format, pagination, filtering, or side effects. It simply states the action without elaborating on any behavioral nuances, adding no value beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), which is concise but under-specified. It lacks any structured information or front-loaded context. While brevity is generally good, this is closer to a placeholder than a useful description, and it fails to convey essential details about the tool's function or output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description is still inadequate. It doesn't explain what pipelines are, what they represent, or what the response contains. An agent cannot confidently invoke this tool or interpret results without prior knowledge. The minimal description fails to meet even basic contextual completeness for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for its only parameter (locationId), including a default behavior note. Per the scoring guide, high schema coverage warrants a baseline of 3 even with no parameter info in the description. The description adds nothing beyond the schema, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Pipelines' is essentially a tautological restatement of the tool name 'opportunities_get_pipelines'. It fails to clarify what pipelines refer to (e.g., opportunity pipelines in a CRM), their purpose, or how they relate to opportunities. It provides no distinguishing information from other 'get' tools, making it vague and unhelpful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of scenarios, prerequisites, or comparisons to sibling tools like 'opportunities_get_opportunity' or 'opportunities_search_opportunity'. An agent receives zero contextual advice on tool selection.
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?
The description adds no behavioral information beyond what annotations already indicate (destructive, idempotent, non-read-only). It does not explain side effects, the semantics of the 'isRemoveAllFollowers' flag, or whether removal is permanent, all of which are important for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no fluff, but it is overly terse—a single phrase that lacks any structure or prioritization of key information. It is not 'front-loaded' with useful context and essentially repeats the tool name's core meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, two required, and no output schema, the description is grossly incomplete. It does not explain the purpose of the parameters, the behavior when 'isRemoveAllFollowers' is true, or any constraints, making it insufficient for an agent to call correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 33% (only 'id' has a description), the description had a responsibility to clarify parameters like 'followers' and 'isRemoveAllFollowers', but it does not mention them at all. It fails to compensate for the schema's sparse documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove Followers' clearly conveys the action (remove) and the resource (followers), and the tool name further specifies it applies to opportunities. It is distinguishable from the sibling 'opportunities_add_followers_opportunity' by the verb, though the description alone lacks the word 'opportunity' to fully disambiguate context without the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, such as the add followers counterpart or any prerequisites. The description is a bare phrase with no context for selection criteria, leaving the agent to infer usage solely from the tool name.
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?
Annotations indicate mutation (readOnlyHint=false) but the description adds nothing beyond the single word 'Upsert'. It does not disclose whether it updates existing opportunities when an id is supplied, how followers are handled, or any side effects. This leaves the agent fully reliant on the schema and annotations with no additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At only two words, the description is under-specified rather than appropriately concise. It lacks any structure (e.g., front-loaded key constraints or context) and fails to convey the operation's complexity, making it unhelpful for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters, nested objects, no output schema, and multiple sibling tools, the description is drastically incomplete. It omits essential information like the expected behavior when id is omitted, the meaning of followersActionType, and return values, leaving the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, meaning several parameters lack descriptions (e.g., assignedTo, monetaryValue, pipelineStageId). The description does not compensate for these gaps at all, nor does it clarify the interaction between required fields like followers and followersActionType. It adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Upsert' and the resource 'Opportunity', which is a specific action that implies create-or-update semantics. However, it does not explain what 'upsert' means in this context or how it differs from the sibling create/update tools, leaving some ambiguity for an agent unfamiliar with the term.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the explicit create or update tools. With siblings like opportunities_create_opportunity and opportunities_update_opportunity, the description provides no criteria (e.g., use if id is present) to route the agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond what annotations already state—such as response format, pagination, or side effects. Since annotations carry the safety burden and the description adds nothing extra, this is a minimal pass.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence), but this is under-specification rather than concise clarity. It fails to include any useful information beyond the name. While it is syntactically minimal, it does not earn conciseness credit because it omits essential context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 should clarify what the returned product object contains, how the optional locationId and sendWishlistStatus affect results, and any edge cases (e.g., slug usage). None of this is addressed. The description is inadequate for an agent to confidently invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are documented in the schema itself. The description does not add any parameter-specific details beyond what the schema provides. Per the calibration baseline for high schema coverage, a score of 3 is appropriate—the description contributes no additional semantic value but does not mislead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Product by ID' is essentially a restatement of the tool name 'products_get_product_by_id'. It states the verb and resource but adds no differentiating detail from sibling product tools like products_get_product_collection or products_get_price_by_id_for_product. It fails to specify what kind of product data is returned or any unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternative product retrieval tools. No context, prerequisites, or exclusions are provided. An agent must infer usage solely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Update Inventory' which implies a write operation, consistent with readOnlyHint=false. However, it adds no detail about side effects, partial updates, required fields, or response behavior. With annotations covering the read/write nature partially, the description adds minimal behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two words) but this is under-specification rather than efficient conciseness. It lacks essential details such as what 'items' should contain, the purpose of altId/altType, and any warnings. A concise effective description should convey necessary information without fluff; this does not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool that updates inventory with an array of items, the description provides no context about the structure of items, expected values, or consequences. Without an output schema, the agent has little guidance on what to pass or what to expect. The complete lack of detail makes the tool hard to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (altId, items, altType), including defaults. The tool description contributes zero additional parameter meaning. According to the rubric, when schema coverage is high, a baseline of 3 is appropriate; the description adds nothing but does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Inventory' is a near-tautology of the tool name 'products_update_inventory'. It does state a verb and resource ('update' + 'inventory') but is extremely generic and does not specify what kind of inventory, which products, or what the update entails. It also fails to distinguish this tool from siblings like products_bulk_update or products_get_list_inventory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or exclusions. An agent has no information to decide between this and other product update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true). The description adds nothing beyond the name – it doesn't mention return format, pagination, or any specific behavior. It provides no additional context beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief ('Get CSV Post') – it is concise but under-specifies. It conveys almost no information beyond the tool name, making it more of a placeholder than a helpful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no output schema and 4 parameters, this description is grossly insufficient. It fails to explain what a 'CSV Post' is, what the response will contain, or how the filtering parameters work. An agent has no idea what to expect or how to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (id and locationId have descriptions; skip and limit do not). The description doesn't add any parameter details – it doesn't clarify what 'CSV Id' means or explain the role of skip/limit. Since coverage is low, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb 'Get' and a resource 'CSV Post', but 'CSV Post' is ambiguous and not clearly distinguished from siblings like social_media_posting_get_post. It does imply a specific category (CSV-related), but the term is unexplained, so it's not a tautology yet lacks precise differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives. No mention of scenarios, prerequisites, or comparisons to get_post or get_posts. The description provides zero context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the baseline for adding context is lower. However, the description adds zero behavioral information beyond the annotations—it does not mention permanence, side effects, cascading deletions, or any operational details. It simply restates the action, providing no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely concise (two words), it is under-specified rather than efficiently written. It lacks any structure or additional context, offering no information that would help an agent. Conciseness is not a virtue when it omits necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description should at least indicate the effect (e.g., permanent deletion) or any required preconditions. The current description is inadequate—it tells an agent nothing about what deletion entails or what to expect. Even with the annotations, the description fails to fill the gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (agentId, locationId) have descriptions in the schema. The description adds no information beyond what the schema already provides. With full schema coverage, the baseline of 3 is appropriate; the description does not enhance parameter understanding (e.g., how to find the agentId).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Agent' is essentially a restatement of the tool name 'voice_ai_delete_agent' and provides no additional specificity. It does not distinguish this tool from siblings like agent_studio_delete_agent or conversation_ai_delete_agent, even though they operate on different agent types. The verb and resource are present but the description is tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. Multiple sibling delete tools exist (agent_studio_delete_agent, conversation_ai_delete_agent, voice_ai_delete_action), but the description offers no context for selecting among them. No prerequisites, exclusions, or scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate this is not read-only, not idempotent, and not destructive, but the description adds no behavioral context. It does not mention that duplicating creates a new ad set while preserving the original, what settings are copied, or what the response contains. With annotations covering the basic mutation profile, the description still fails to add any value about side effects or outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and avoids verbosity. However, it is so under-specified that it borders on useless. It is not bloated, but it also does not earn its place by conveying necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and no output schema, the description must explain the tool's return value (e.g., the new ad set ID) and any side effects. It does neither. The description is completely inadequate for an agent to call this tool correctly, providing no information about the outcome or expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, adsetId, has zero schema description coverage, and the description also provides no explanation of its format, how to obtain it, or whether any additional parameters are implied. Since schema coverage is 0%, the description must compensate but does not, leaving the agent to guess at the parameter's semantics beyond its name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Duplicate ad set' names the action (duplicate) and resource (ad set), which is clear at a basic level. However, it adds no detail about what duplication entails (e.g., does it create a new copy, copy targeting/budget, or require a name change?), and it offers no differentiation from sibling tools like duplicate_ad or duplicate_campaign beyond the resource type. It is essentially a restatement of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many sibling duplication tools, nor any prerequisites (e.g., an existing ad set ID, required permissions, or whether an integration must exist). The agent is left with no information about selection criteria or invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds no behavioral context beyond these annotations—it does not state what data is searched, what the results contain, or any side effects. While it doesn't contradict the annotations, it provides zero additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, a single phrase that lacks a full sentence. While it is concise, it is not informative; it under-specifies the tool's purpose and provides no structure to guide an agent. It is not just concise but terse to the point of being useless.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with three parameters and no output schema, the description should at least state what kind of targeting options are searched (e.g., Facebook's targeting criteria) and what the response looks like. It does neither, leaving an agent with no idea what this tool does or how to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—the schema describes all three parameters (type, query, searchType) with meaningful descriptions. The tool description adds no extra information about these parameters, so the baseline of 3 is appropriate. There is no need to penalize further, but no enhancement either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search targeting options' is essentially a restatement of the tool name 'search_targeting'. It does not specify that this is for Facebook ad management, what 'targeting options' means, or what kind of search is performed. There is no differentiation from sibling tools like ad_manager_google_search_targeting or ad_manager_li_search_targeting, making it ambiguous for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternative targeting search tools on other platforms (e.g., Google or LinkedIn). There is no mention of prerequisites, scenarios, or conditions under which this tool is appropriate. The description offers no context to help an agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds zero behavioral context—it does not disclose return format, pagination, date formatting, or any other traits that an agent would need to anticipate the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words, but this is under-specification rather than concise, effective writing. It lacks any structured information such as a clear scope or usage note, making it unhelpful despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters (four required) and no output schema, this description is grossly inadequate. It fails to explain what reporting data is returned, how dates are formatted, what fields like 'cost_micros' represent, or how the groupBy parameter affects results. An agent cannot call this tool correctly based on this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% description coverage for all six parameters, so the agent has baseline documentation. The description adds no additional meaning or clarification beyond what is already in the schema, so it earns the baseline 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get reporting data' is a generic phrase that merely restates the tool name without specifying the resource (Google Ads reporting) or its scope. It does not distinguish this from sibling reporting tools like ad_manager_google_get_reporting_list or ad_manager_google_get_campaign_reporting, leaving the agent uncertain about what exactly this tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many alternate reporting tools. The description does not mention any exclusions, prerequisites, or alternatives, so an agent cannot determine the appropriate context for invoking this specific function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations indicate readOnlyHint=false and destructiveHint=false, the description itself adds no behavioral context. It does not state what side effects execution has, whether it requires authentication, how long it may take, or what happens on failure. Given the annotations exist, some burden is lifted, but the description contributes nothing beyond the vague phrase 'Execute Agent'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse—only two words—which is under-specification rather than purposeful concision. It lacks any front-loaded critical information, such as the need for an agent ID and message, or the session management nuance of executionId. While brief, it fails to earn its place by omitting essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, nested objects, no output schema, and no behavioral annotation beyond hints, the description is completely inadequate. It does not explain how the execution works, what a successful response looks like, or how to handle sessions and versions—all of which are covered in the parameter descriptions but not in the tool-level text. An agent cannot reliably call this tool correctly based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 78%, meaning most parameters have descriptions in the schema itself (e.g., message, contactId, executionId). The tool description does not add any parameter-level meaning. Since coverage is above 50% but not >80%, a baseline of 3 is applied per the rubric, and nothing in the description pushes it higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Execute Agent' directly restates the tool name, providing no additional verbs, resources, or scope. It does not distinguish this tool from sibling tools like agent_studio_execute_agent_deprecated or other execute-related tools, leaving the agent to infer what 'execute' means in this context. This is a tautology that adds no clarity beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. For example, it does not mention that this tool runs an agent synchronously, how it relates to creating or managing agents, or when to use the deprecated version. An agent has no basis to decide between this and similar tools based on the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (it's a mutation) and idempotentHint=true, but the description adds no behavioral context beyond that. It doesn't mention side effects, such as triggering automations (referenced by toNotify parameter) or the interplay of rrule with ignoreFreeSlotValidation. Given the annotations are present, this minimal addition slightly exceeds zero but is still very thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
'Update Appointment' is technically concise but under-specified to the point of being unhelpful. It's a two-word tautology of the tool name. It doesn't front-load any useful information and fails to earn its place as a description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 16 parameters, complex logic around recurrence rules, slot validation, and meeting locations, and no output schema, the description is severely inadequate. It provides zero context about the operation's scope, prerequisites, or return behavior. Agents have no clue about the complexity involved, making this tool almost unusable from a description standpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 94% of parameters with descriptions, so the baseline is 3. The description itself adds nothing about parameters, but since the schema is comprehensive, the agent can rely on that. The description does not clarify any parameter meaning beyond what's already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Appointment' clearly states the action (update) and resource (appointment). However, it is extremely generic and does not differentiate from sibling tools like calendars_create_appointment or calendars_get_appointment. It lacks any scope or details that would help an agent distinguish it from other calendar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, when not to use it, or which alternatives exist. The description is a bare statement with no context about prerequisites, typical use cases, or exclusions. An agent would have no way to know if this is the right tool versus calendars_edit_block_slot or calendars_update_schedule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no behavioral context beyond 'Get Free Slots'—it does not mention what constitutes a free slot, how results are structured, pagination, or edge cases. With annotations present, the bar is lower, but the description still fails to provide any additional useful behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise in length, but it is under-specified. It does not earn its place because it omits essential information. The structure is acceptable, but the extreme brevity leaves the description useless beyond a minimal label.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters and no output schema, the description is severely inadequate. It fails to explain the return format, the meaning of free slots, the required calendarId context, timezone handling, or the 31-day limit (even though that is in the schema). An agent cannot confidently invoke this tool based solely on the description without inferring from the schema and tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters already have descriptions in the input schema. The description does not add any parameter-specific meaning beyond what the schema provides, such as clarifying the 31-day date range constraint or explaining the difference between userId and userIds. Since the schema already documents the parameters thoroughly, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Free Slots' states a verb and a resource, giving a basic sense of the operation. However, it does not specify that these are calendar free slots or distinguish this from sibling tools like calendars_get_blocked_slots or calendars_get_calendar_events. It is not a tautology but lacks the specificity needed for an agent to clearly understand the tool's unique purpose without examining sibling names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or situations where this tool should be preferred. An agent would have no idea why to pick this over calendars_get_blocked_slots or other calendar-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state readOnlyHint=false and destructiveHint=false, which already indicate a non-read, non-destructive operation. The description adds no context about whether tags are added, removed, or overwritten, nor about the 'removeAllTags' option. It fails to disclose the actual behavior beyond the generic 'update' verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, but it is under-specified and fails to convey essential information. It is not concise in a beneficial way; it omits critical details about the tool's operation and parameters, making it closer to a placeholder than a useful summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, no output schema, and no enums. The description provides no information about the 'type' parameter's role, the semantics of removeAllTags, or how this relates to other tag management tools. It is completely inadequate for an agent to call this tool correctly without additional external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (tags, type, contacts, locationId, removeAllTags) is already documented in the schema. The description adds no additional meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Contacts Tags' gives a verb and resource, but 'update' is vague and could mean add, remove, or overwrite. The tool name 'contacts_create_association' suggests creating associations, while the description says 'update', which is inconsistent. It does not differentiate from siblings like contacts_add_tags or contacts_remove_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the more specific sibling tools contacts_add_tags and contacts_remove_tags. It does not mention the 'type' parameter or the use case for bulk association management, leaving the agent to infer usage from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' adds no new behavioral context. It does not mention permanence, side effects, or any other operational traits that an agent needs 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Delete a template'), which is concise but under-specified. It does not include essential context such as the scope of deletion or any caveats, so it is not appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a destructive action, no output schema, and 50% parameter coverage, the description is incomplete. It lacks details about what constitutes a template, how deletion affects related data, or how to distinguish from similar delete operations, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only locationId has a description), but the description provides no parameter meanings at all. It does not explain templateId or reinforce the default behavior of locationId, leaving the agent with insufficient semantic information for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action (delete) and resource (template), but 'template' is vague without the tool name providing the 'email' context. It does not differentiate from other delete-template siblings like locations_delete_an_email_sms_template, making the purpose only moderately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as emails_update_template or locations_delete_an_email_sms_template. No conditions, exclusions, or selection criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, covering the safety profile. The description adds no behavioral context beyond the basic action—no mention of pagination, default location, filtering behavior, or rate limits. It adds no value beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but it is under-specified rather than appropriately concise. It lacks essential information that would justify its brevity, and there is no structuring or front-loading of key constraints since none are mentioned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, 2 required, and no output schema, the description is inadequate. It gives no information about pagination, response format, or the meaning of the parameters. An agent would not know how to correctly call this function without making significant assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only locationId has a description). The description does not explain any parameter: it doesn't mention that limit and offset are required, what search filters, or that locationId defaults to GHL_LOCATION_ID. It completely fails to compensate for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action: 'Fetch List of Redirects' – a clear verb and resource. It distinguishes this from sibling tools that create, delete, or update redirects, as this is the only list tool for redirects. However, it doesn't explicitly state the scope (e.g., all redirects for a location or a specific funnel) beyond what the tool name suggests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. An agent would have no idea why to choose this over other funnel-related list tools (e.g., funnels_get_pages_by_funnel_id).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral traits beyond the annotation destructiveHint=true. It does not mention irreversibility, potential cascading effects, or that the operation is permanent. Since the annotation already indicates it is destructive, the description could have added context like 'this cannot be undone' but did not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, only two words. While this is not verbose, it is under-specified and does not earn its place by adding value beyond the tool name. It is not front-loaded with richer context; it is simply minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description should at least indicate that the operation is permanent or require confirmation. The description provides no context about behavior on error, such as what happens if the estimate ID is invalid. The schema covers parameters, but overall the description is inadequate for an agent to understand the consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters (altId, altType, estimateId). The description adds no additional parameter semantics. Baseline of 3 is appropriate because the schema already fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Estimate' is essentially a restatement of the tool name 'invoices_delete_estimate'. It provides no additional specificity beyond the obvious verb and resource. It does not distinguish between deleting an estimate and deleting an estimate template or invoice, which are siblings. The purpose is clear but tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like invoices_delete_estimate_template or invoices_delete_invoice. There is no mention of prerequisites, such as the estimate needing to exist or be in a certain state, nor any indication of when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds no extra information about side effects (e.g., whether the schedule is permanently removed, what happens to associated invoices). The description merely repeats the verb 'delete' without disclosing consequences beyond what annotations already imply. No contradiction, but no additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is overly terse—just two words. While it is short, this is under-specification rather than concise efficiency. It lacks any structured detail, making it hard for an agent to know the full scope of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with three parameters and no output schema, the description is seriously inadequate. It does not mention what a schedule is, what happens on deletion, potential side effects, or any restrictions. The agent would need to infer everything from the name and schema, which is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (altId, altType, scheduleId) are already documented in the schema. The description provides no additional parameter semantics or usage hints. Baseline 3 is appropriate given the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'delete' and resource 'schedule', which is clear at a basic level, but it lacks specificity about the schedule type (invoice schedule) and does not differentiate from semantically close siblings such as invoices_cancel_invoice_schedule or invoices_update_invoice_schedule. The tool name provides the invoice context, but the description itself is too terse to uniquely identify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description gives no context about prerequisites, whether to prefer this over cancel or update operations, or any exclusions. An agent would have no clue when to invoke this against the many other schedule-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral detail—no mention of pagination, filtering behavior, or return structure. With annotations present, the bar is lower, but the description still contributes nothing beyond the annotation-derived information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, this is under-specification rather than effective conciseness. It lacks any structure or organization. While it's brief, it omits essential information, making it more of a stub than a concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no output schema, and a vague two-word description, this is severely inadequate. The agent has no idea what schedules are, what filters exist, how pagination works, or what the response will look like. Even with annotations covering safety, the description fails to provide the operational context needed to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 9 parameters already have descriptions in the schema. The description itself adds no parameter context, but the baseline of 3 applies because the schema carries the semantic weight. No extra meaning is provided by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List schedules' provides a verb and resource, and the tool name clarifies it's about invoice schedules. However, it doesn't distinguish itself from siblings like invoices_list_invoice_templates or invoices_list_estimates, and it gives no sense of scope or filtering. It's minimally clear but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The sibling list includes many invoice-related tools, but the description offers no context about when listing schedules is appropriate, nor any exclusions or prerequisites. An agent would have to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. However, the description adds no behavioral context beyond that—no mention of return format, pagination, or what a search actually does. It is a single word that adds zero value over 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single word—but this is under-specification rather than effective conciseness. It is not appropriately sized because it omits essential information that an agent needs to determine whether and how to call the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 optional parameters and no output schema, an agent has no clue what this tool returns, what the search scope is, or how these parameters shape the query. The name hints at 'locations', but the description leaves everything to inference. This is severely inadequate for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes 4 of 5 parameters (skip, limit, order, companyId) with clear descriptions, leaving only 'email' undocumented. The tool description itself provides no parameter clarification, but since schema coverage is high (80%), it partially compensates. Still, the description fails to explain the search criteria or how parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description is simply 'Search', which restates the verb portion of the tool name without specifying the resource. It fails to indicate that it searches locations, making it a near-tautology that provides no distinguishing information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'locations_task_search' or 'locations_get_location'. No context is provided about typical use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no extra behavioral context—nothing about rate limits, authentication needs, or what happens during the call. It is consistent with the annotations but discloses no additional traits. The description adds minimal value beyond the structured metadata, so a score of 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise in terms of word count, but it sacrifices content for brevity. It is underspecified—essentially a title rather than a useful description. While there is no wasted wording, the lack of information makes it an ineffective structure. It achieves conciseness at the expense of clarity, meriting a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no explanation of what 'installer details' are or what the response contains. The description is too vague to tell an agent what the tool returns. With only a single parameter and no return documentation, the description fails to provide adequate context for correct invocation and interpretation of results. This is a significant gap for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a full description for the single parameter 'appId' ('ID of the app to get installer details'), giving 100% coverage. The description does not add any further meaning—no format, constraints, examples, or caveats beyond what is in the schema. Per the rubric, with high schema coverage the baseline is 3, and the description provides no bonus. Thus, a score of 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Installer Details' is a verb-plus-resource restatement of the tool name, but it does not explain what 'installer details' actually are or what the resource encompasses. It adds no elaboration beyond the name and does not differentiate the tool from siblings (e.g., marketplace_get_charges, marketplace_get_specific_charge). This is essentially a tautology—repeating the title without clarifying the output or scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any context, prerequisites, or exclusions. There is no reference to related marketplace tools or conditions that would lead an agent to choose this one over others. The agent is left with no decision-making information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral traits are disclosed. The description is a single terse phrase that does not indicate what side effects occur, whether it overwrites existing data, requires specific permissions, or returns anything. With no annotations providing hints (readOnlyHint=false, openWorldHint=true), the description carries the full burden, and it fails to provide any transparency about what the tool actually does beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one short sentence) but not appropriately structured or informative. It lacks any front-loading of critical information beyond the name. While brevity can be good, here it sacrifices all explanatory value, making the tool cryptic. The sentence is not misleading, but it is under-specified to the point of being nearly useless guide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, no output schema, and significant complexity (nested objects, conditional fields), this description is woefully incomplete. It does not explain the migration context, prerequisites, what happens to existing connections, or any side effects. An agent cannot safely invoke this tool without additional documentation. The description must compensate for the schema's lack of high-level guidance, and it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with each parameter described, so the baseline is 3. However, the description adds no additional meaning or context about how parameters relate to the migration process. It does not clarify how 'type', 'appId', or 'accountId' interact or what 'migrate' entails for these fields. The description is essentially redundant with the schema, providing no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Migrate') and resource ('external authentication connection'), but the exact nature of the migration is ambiguous—it could mean moving, updating, or transferring. It doesn't differentiate from sibling tools (none other use 'migrate'), but the purpose is generic enough that an agent might not know what action to take without more context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The sibling list contains no other migration tool, but the description does not explain scenarios (e.g., transferring a connection between apps, updating credentials). An agent would have to infer usage from the schema alone, which is insufficient for a complex operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-read-only, non-destructive operation, so the description's burden is to add behavioral context. It merely says 'Update' without explaining what side effects occur, whether changes are reversible, what fields are mutable, or any authorization requirements. The description adds no value beyond the annotations and leaves important behavioral details unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Update File/ Folder'), which is not conciseness but under-specification. It lacks any structure or front-loaded essential details. Every word is generic and fails to convey the tool's specific behavior. It is not helpful for an agent trying to understand the tool's use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with four parameters (two required) and no output schema, this description is grossly incomplete. It does not explain what happens if the id does not exist, whether the update is partial or full, or any limitations (e.g., only renaming). The agent is left to guess the exact semantics, making this inadequate for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so every parameter already has a clear description (id, name, altId, altType). The description 'Update File/ Folder' does not add any semantic nuance beyond what the schema provides. Given high schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and a resource ('File/ Folder'), so the basic purpose is understandable. However, it does not specify what aspects can be updated (e.g., name, ownership) beyond what the schema implies, and it does not distinguish itself from the sibling 'medias_bulk_update_media_objects' which obviously operates on multiple objects. The phrasing is generic and could apply to any 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is absolutely no guidance on when to use this tool versus alternatives such as 'medias_bulk_update_media_objects' or 'medias_create_media_folder'. The description provides no context about scenarios (e.g., renaming a single file vs bulk rename) or prerequisites (e.g., the object must already exist). An agent has to infer everything from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds nothing about what side effects occur, whether notifications are sent (the notifyCustomer param hints at this), or what happens upon success/failure. The description is a bare 'Create order fulfillment' and does not elaborate on the operation's behavior beyond what the schema already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of three words, which is under-specified rather than concise. It omits essential context such as fulfillment meaning, required fields, and behavior. While brevity is a virtue, this is so minimal that it fails to convey any useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters (4 required), including nested arrays and a boolean, the description is grossly incomplete. There is no explanation of what constitutes a fulfillment, how trackings should be structured, the implications of notifyCustomer, or any error handling. With no output schema and no supplementary detail, an agent cannot reliably determine how to construct a valid request or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, but they are minimal and one is potentially misleading: orderId is described as 'ID of the order that needs to be returned,' which suggests a return/refund context rather than fulfillment. The tool description itself provides no additional meaning for parameters like items or trackings, so it adds zero value beyond the schema. The high schema coverage earns a baseline of 3, but the misleading orderId description and lack of elaboration reduce the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('create') and resource ('order fulfillment'), which distinguishes it from list/get tools like payments_list_order_fulfillment. However, it is extremely terse and does not explain what 'order fulfillment' entails, leaving the agent to infer its meaning from the parameter names. It is functional but not specific enough to fully disambiguate from other payments write operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as payments_record_order_payment or payments_create_integration. There is no mention of prerequisites, order status requirements, or scenarios where this tool is not appropriate. The agent has to guess from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds nothing beyond the annotations (destructiveHint, idempotentHint). It doesn't clarify consequences like permanence, effect on linked posts, or whether the action is reversible. There is no contradiction with annotations, but also no added 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is under-specification rather than effective conciseness. It lacks structure and fails to communicate essential information, making it a fragment rather than a useful sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description is completely inadequate. It omits what happens on deletion, return values, or any caveats. The agent must rely entirely on the name and schema, which is insufficient for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all four parameters, including the default behavior of locationId. The description itself adds no parameter detail, but since the schema already handles this, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Account' is essentially a restatement of the tool name, providing no additional specificity about what type of account is deleted or what the deletion entails. It doesn't differentiate from sibling tools like delete_post or delete_csv, leaving the agent to infer meaning from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention scenarios, prerequisites, or exclusions, leaving the agent without context for making a correct selection among the many social media posting tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which communicate that this is a non-destructive write operation. The description adds no additional behavioral context such as side effects, authentication requirements, or rate limits. It only says 'Edit post', providing zero value beyond the 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is under-specified rather than concise. It consists of only a two-word phrase that contains no useful detail. It is not structured or front-loaded with key information, and the brevity is not a virtue because it omits all valuable context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of this tool—18 parameters, nested objects, no output schema, and platform-specific constraints mentioned in the schema—the description is severely inadequate. It does not explain the edit semantics, platform limitations, or any operational expectations. The agent has no guidance beyond the raw schema, which is insufficient for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all 18 parameters have descriptions in the input schema. According to the rubric, a high coverage (>80%) establishes a baseline of 3 even without parameter information in the description. The description itself offers no parameter-specific explanations, so it does not increase the score, but it also does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Edit post' is essentially a tautology that restates the tool name (social_media_posting_edit_post). It provides no additional specificity about the resource or scope, and it does not differentiate from sibling tools like social_media_posting_create_post or social_media_posting_delete_post. It is only a vague restatement of the intended action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios, or exclusions. For instance, it does not clarify when editing is appropriate versus deleting or creating a post, nor does it mention any relationship to other social media posting tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=false and destructiveHint=false, so the description need not repeat that. However, it adds no behavioral context beyond the verb 'set' – no mention of side effects, whether existing locations are overwritten, required permissions, or response behavior. The openWorldHint=true suggests uncertain behavior, but the description provides no clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler, which is concise. However, the brevity contributes to its inadequacy – it is under-specified rather than efficiently informative. The structure is simple, but every word adds little beyond the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, 2 nested objects, no output schema, no descriptions for the nested objects), this description is severely incomplete. It omits what the 'location' object should contain, how 'account' relates to 'accountId', and the expected response format. An agent cannot confidently invoke this tool correctly based on the available information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides zero information about parameters. The schema lists 5 parameters, with 'account' and 'location' being unstructured objects with no descriptions (additionalProperties: {}) – the description does nothing to explain these critical inputs. With schema coverage at 60%, the description should compensate for the undocumented parameters but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Set google business locations'), which is specific and distinguishes it from the sibling social_media_posting_get_google_locations. However, it essentially restates the tool name with no additional nuance about what 'set' means (e.g., create, update, replace). It is not a tautology but adds little beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, typical scenarios, or how it differs from related tools like set_accounts or get_google_locations. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context such as side effects, dependencies, or error conditions. It merely restates the tool's basic function without enriching the annotation-provided information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (four words), which is concise, but it sacrifices essential information. It does not front-load any differentiating details or use cases. Conciseness is fine, but the under-specification makes it insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters, nested objects, and no output schema, the description provides almost no contextual completeness. It does not explain what the tool returns, how it relates to shipping zones vs rates, or any operational nuances. This is far below the minimum viable for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The tool description adds no additional semantic meaning beyond what the schema already provides. Thus, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('get') and a resource ('shipping rates'), but the tool name refers to 'shipping zones,' creating ambiguity. It does not distinguish from sibling tools like store_get_shipping_rates or store_get_shipping_zones, so an agent cannot easily tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context, prerequisites, or exclusions are provided. The description is a single sentence with no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations, which already declare readOnlyHint, destructiveHint=false, idempotentHint, and openWorldHint. While there is no contradiction, it also fails to mention any specifics like pagination, default location behavior (though locationId schema does), or what a survey object contains, offering no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
'Get Surveys' is extremely brief, but this is under-specification rather than effective conciseness. It sacrifices essential context for brevity, providing no structure or useful information that justifies its minimal length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (including undocumented ones) and no output schema, the description is grossly incomplete. It does not explain the meaning of 'type' or 'skip', nor does it describe the return format or any filtering behavior, leaving an agent under-informed for a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only limit and locationId have descriptions), yet the tool description does not help with the undocumented parameters 'skip' and 'type'. It adds no meaning beyond the schema, failing to compensate for the uncovered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Surveys' states a clear verb and resource, but it is nearly a tautology of the tool name and does not distinguish this from the sibling surveys_get_surveys_submissions. It communicates the basic action but offers no nuance about scope or filtering, so it is minimally clear but not informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is absolutely no guidance on when to use this tool versus alternatives. No mention of the sibling surveys_get_surveys_submissions or any exclusion conditions, leaving the agent without direction on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true. The description does not add any behavioral context beyond these, such as side effects (campaign stops spending) or reversibility (the existence of a resume tool). It neither contradicts annotations nor enriches them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, it is extremely brief, but this is under-specification rather than conciseness. It omits critical information that an agent would need, making the brevity a deficiency rather than an asset. The description does not earn its place by conveying necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description is severely incomplete. It does not explain what pausing a campaign entails (e.g., stopping delivery, impact on budget), whether it is reversible, or any prerequisites. An agent cannot reliably invoke this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: campaignId lacks a description in the schema, and the tool description does not explain what the campaign ID refers to (e.g., Facebook campaign ID). locationId has a description in the schema, but the description does not compensate for the undocumented campaignId or clarify how they work together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Pause campaign' clearly identifies the action (pause) and resource (campaign), which is specific enough. However, it does not differentiate from sibling tools like ad_manager_fb_pause_ad or ad_manager_fb_pause_adset. The name already includes 'fb' and 'campaign', so the purpose is reasonably clear, but the description adds no distinguishing scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention that it should be used specifically for pausing campaigns rather than ads or ad sets, nor does it provide any prerequisites or contextual triggers. The agent is left to infer that it applies to campaigns from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no behavioral detail beyond the bare action; it does not mention idempotency, side effects, or any operational constraints. It does not contradict annotations, but it fails to provide useful context like what happens if a default is already set.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (four words) but under-specifies the operation. It does not front-load key information like the impact or scope. Conciseness alone is not a virtue when it sacrifices essential context; this is closer to being too terse than appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating operation with no output schema and only two parameters, the tool description is minimal. An agent would need to infer what 'default page' means, whether it applies to a specific ad account, and what the effects are. The description is inadequate for reliable tool selection without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both pageId and locationId having clear descriptions in the input schema. The description adds nothing beyond the schema, which is acceptable given full schema coverage. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('Set default page') which conveys a specific action, but it lacks context about what a 'default page' means (e.g., for which ad account or integration). It does not distinguish it from sibling tools like ad_manager_fb_attach_page or ad_manager_fb_get_pages, but it is not a pure tautology and suggests a clear operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no context about prerequisites (e.g., needing an existing Facebook integration), and no mention of when it should be preferred over similar set/attach operations. The description provides zero usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate idempotentHint=true and destructiveHint=false, so the description doesn't need to cover those basics. However, the description adds no behavioral context beyond the name itself—no mention of what happens on create vs. update, how existing fields are handled, or any side effects. It merely restates the tool's purpose, providing zero 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—only two words—but this reflects under-specification rather than efficient compression. It provides no context, no examples, and no structural guidance. While there is zero waste, the extreme brevity fails to earn its place as a useful descriptor, similar to the 'under-specification' case in the calibration low example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters, some enums, and no output schema, this description is grossly incomplete. It doesn't explain the upsert behavior (e.g., whether it overwrites all fields or only provided ones), how the 'id' parameter distinguishes create vs. update, or any integration requirements. The agent would need to infer all context from the name and schema, which is insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters are fully described in the schema (100% coverage), including types, enums, and defaults. The description itself contributes no additional parameter information, but since the schema carries the full burden, a baseline of 3 is appropriate. The description does not clarify relationships between parameters or usage patterns beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert campaign' states a clear verb and resource, indicating the tool creates or updates a campaign. It distinguishes itself from sibling tools like get_campaign, pause_campaign, or publish_campaign through the verb 'upsert'. However, it doesn't elaborate on what specific aspects of the campaign are managed or how it differs from upsert_ad or upsert_adset, so it lacks deeper differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention whether to use upsert for both creation and update scenarios, when a get_campaign is preferred, or if any prerequisites (like an existing integration) are required. There is no mention of alternatives or exclusions, leaving the agent without routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which align with an upsert operation. However, the description adds no additional behavioral context—it doesn't explain what happens to existing pixels, any side effects, or permission requirements. It neither contradicts nor enriches the annotations, so it provides minimal value beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely concise (a single phrase), it is under-specified rather than efficiently concise. It lacks any explanatory structure or front-loaded key information. The phrase 'Upsert conversion pixel' is not a useful summary; it is merely a restatement of the name, failing to convey any actionable details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation operation with 5 parameters and no output schema, the description is incomplete. It doesn't explain what an upsert does to existing pixels, what constitutes a valid pixel, or any dependencies (e.g., requires an ad account or integration). The agent has no idea what to expect in terms of return values or side effects, making the tool difficult to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 5 parameters with descriptions, achieving 100% coverage. The description adds no parameter-specific semantics, so it relies entirely on the schema. Given the high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert conversion pixel' is essentially the tool name with spaces inserted. It restates the name without adding any specificity about what an upsert entails, what a conversion pixel is, or how it differs from sibling tools like ad_manager_fb_get_pixels or ad_manager_fb_upsert_ad. This is a tautological restatement rather than a clear explanation of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or scenarios where one might use get_pixels for reading or create_integration for setup. The agent is left without any contextual instructions to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond that—it doesn't mention whether pagination is supported, whether results are filtered by location, or what fields are returned. With no output schema, the description should provide some behavioral expectation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), but it is not appropriately sized—it omits essential details such as what a segment is, what the output looks like, or how it differs from related tools. While it is concise, it lacks necessary information, making it under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters, no output schema, and no usage guidance, the description is severely incomplete. It fails to explain what segments are in this context, the effect of the 'type' parameter, or the response format. An agent would have to infer too much to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema provides basic descriptions for both parameters ('Segment type' and 'Location identifier...'). The tool description adds nothing beyond this, so it meets the baseline of 3. However, the schema's parameter descriptions are themselves minimal (e.g., 'Segment type' is tautological), so the value provided is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get segments' states a verb and resource but is extremely vague. It does not distinguish this tool from the sibling 'ad_manager_google_get_segment_by_id', which presumably retrieves a single segment, nor does it clarify what type of segments (e.g., audience, ad groups) are being retrieved. The name itself is more informative than the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'ad_manager_google_get_segment_by_id' or even the upsert/delete segment tools. The description fails to mention the intended use case (e.g., listing all segments) or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds no behavioral context beyond the verb 'Update' — it does not clarify whether fields are partially updated (PATCH-like) or replaced (PUT), or mention any required permissions or side effects. It fails to add value beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Update Agent Metadata') and front-loaded with the action, but it is under-specified to the point of being unhelpful. Concise does not mean vague; a good description should add context within a few sentences. This fails to earn its place by omitting critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema, the description is insufficient. It does not explain what the update affects, whether it requires an existing agent, what happens on success, or any limitations. An agent would need to explore the schema and sibling tools to use this correctly, which the description should have addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 67% of parameters with descriptions (name, status, description, locationId), and the description adds no extra parameter meaning. According to the baseline, when schema coverage is high (>80% but here 67%), a score of 3 is appropriate because the description does not compensate for the undocumented parameters (agentId, source).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Update') and a resource ('Agent Metadata'), but does not specify which metadata fields are affected or distinguish it from other agent update operations. It is not a tautology, but it is vague about scope, leaving the agent to inspect the schema to understand what can be changed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of alternatives like agent_studio_update_agent_version, nor does it mention any prerequisites (e.g., the agent must already exist). There is no mention of context or exclusions, so an agent has to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the creation behavior is implied. However, the description adds no additional context about what happens during creation—no mention of required permissions, side effects, or relationships to other resources. It merely states the action without enriching the behavioral model provided by 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence that essentially restates the tool name. While it is short, it is not effectively structured: it does not front-load important differentiators or provide any substantive content. The sentence does not earn its place because it adds no value beyond the tool title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, enum for resourceType, constraints on calendarIds), the description is grossly inadequate. It provides no context about the creation process, required fields, or expected outcomes. With no output schema to fall back on, the description should outline what the creation entails, but it offers only the bare action name. An agent using this tool would lack essential information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (6 of 8 parameters have descriptions), which is moderate but not high enough to warrant a baseline of 3. The tool description adds nothing about parameter semantics—it does not explain how resourceType selects equipment vs. rooms, the relationship between quantity and outOfService, or the mapping constraints for calendarIds. The schema carries the burden, but the description fails to provide additional interpretive guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and object ('Create Calendar Resource'), which identifies the action and resource type. However, it does not differentiate from sibling tools like calendars_create_calendar or calendars_create_calendar_group, which are also create operations in the same domain. The purpose is clear but lacks distinguishing context that would help an agent select this tool among its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or exclusions. The agent is left to infer usage from the name alone, and no information is given about how this differs from creating a calendar or a calendar group.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context such as pagination behavior, sorting, or the fact that it returns a list. With annotations present, the description should add extra context, but it does not, so it only meets the baseline expected of 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is under-specified rather than concise. It lacks a complete sentence and provides no structure to guide an agent. The brevity is not a virtue because it omits essential details, resulting in a poor trade-off between length and utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool requires appointmentId, limit, and offset, yet the description does not explain that notes are tied to a specific appointment, that pagination is necessary, or what the return type is. With no output schema, the description should clarify these aspects, but it does not. The description is incomplete for an agent to know how 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: limit, offset, and appointmentId are each described in the schema. The tool description adds no additional meaning beyond these, but since the schema is complete, the baseline is a 3. The description does not contradict or mislead, but it also does not enhance the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Notes' is barely more than the tool name. It lacks the context that these are appointment notes and doesn't specify for which appointment or how they are retrieved. It does not distinguish from any other 'get' tool and is essentially a tautology, adding no new information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus alternatives. No context about prerequisites, pagination, or the need for an appointment ID is provided. The description offers zero guidance on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. However, the description adds no behavioral context beyond that—no mention of return format, fields, or error handling. It fails to disclose anything about what the tool returns or any nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified rather than concisely informative. It is only two words, which is too sparse to be useful. It does not earn its place by conveying necessary details; it is closer to a stub than a concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that fetches a single resource, the description lacks essential context: what fields are returned, whether it requires special permissions, or what a 'calendar' represents. It is not complete enough for an agent to understand the tool's behavior, despite the simple interface.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers the single parameter (calendarId) with a description 'Calendar Id' at 100% coverage. The description adds no additional meaning about the parameter, but since the schema already provides the necessary info, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Calendar' states a clear verb and resource, but it lacks specificity about what a 'calendar' is in this context and does not differentiate from sibling tools like calendars_get_calendars (plural) or other calendar-related getters. It is not a tautology but is minimal and generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention that it retrieves a single calendar by ID, or that calendars_get_calendars should be used for listing. The description provides zero context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral insight—it doesn't explain what events are returned, how filtering works, or any default behavior. It provides zero added 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is concise (a single phrase), it is under-specified to the point of being unhelpful. It fails to convey the tool's purpose or context, making it an inadequate substitute for a proper description. It is not 'appropriately sized' because it omits essential information that an agent needs to understand the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (2 required) and no output schema, this description is woefully incomplete. An agent cannot infer the tool's function, semantics of the time range, or how the user/group/calendar filters apply from the description alone. It relies entirely on schema descriptions, which may not convey the overall behavior and expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a descriptive label (e.g., startTime, endTime, userId). The description adds no additional meaning to the parameters. Since the schema fully documents them, the baseline of 3 is appropriate, but the description neither enhances nor clarifies parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Calendar Events' is a direct restatement of the tool name, providing no additional specificity. It does not distinguish this tool from siblings like 'calendars_get_calendars' or 'calendars_get_appointment', nor does it mention that it operates on events within a time range. It is a tautology that adds no value beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of required parameters, typical use cases, or exclusions. The description gives no context that would help an agent decide between this and other calendar-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. However, the description adds no behavioral detail beyond the tool name itself—it does not state what data is returned, whether notes are filtered by anything else, or any edge cases. With annotations present, the bar is lower, yet the description still contributes nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (three words), but this is under-specification rather than good conciseness. It lacks essential context about the resource and its scope, making it less helpful than a slightly longer description that clarifies usage. It does not front-load important constraints or relationship to siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of sibling tools like contacts_get_note and contacts_get_all_tasks, the description is incomplete because it does not explain what 'All Notes' means relative to a contact. It also does not mention that it requires a contactId, despite that being the only parameter. While the schema provides the parameter, the description fails to connect it to the tool's purpose, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required parameter 'contactId' with a description 'Contact Id', which is minimal but sufficient. Schema description coverage is 100%, so the baseline is 3. The tool description does not elaborate on the parameter or how it is used, so it adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get All Notes' conveys a verb and resource, but it is ambiguous about scope and does not differentiate from sibling tools like contacts_get_note (singular) or contacts_get_all_tasks. An agent cannot tell what 'All' refers to without reading the schema, and it does not distinguish this from other note-related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention that it requires a contactId or that it returns all notes for a specific contact, nor does it contrast with contacts_get_note or contacts_create_note. An agent is left without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds no behavioral context beyond that—no mention of return format, error conditions, or what exactly constitutes a 'Contact'. Given the annotations, the description contributes minimal additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is under-specified rather than helpfully concise. It lacks any structured information or meaningful content, and does not front-load any useful nuance. It essentially repeats the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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, the description should at least indicate what a Contact is, what fields are returned, or any caveats (e.g., 'returns full contact object'). None of this is present. The description is incomplete even for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter (contactId with description 'Contact Id'), so 100% schema coverage exists. The description does not add any extra meaning beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('Get') and resource ('Contact'), which is clear enough but lacks specificity. It doesn't distinguish from other contact tools like 'get_contacts' or 'get_duplicate_contact', and doesn't explicitly state it retrieves by ID (though the parameter implies it). It's not a tautology but is extremely generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools in the contacts domain (e.g., contacts_get_contacts, contacts_search_contacts_advanced), the lack of any context or exclusions is a critical omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description does not need to restate those. Beyond that, the description adds no behavioral context—it does not mention side effects, what happens if the contact is not in the campaign, or any authorization requirements. Given the annotations, the description contributes nothing extra to behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is under-specified. It merely repeats the tool name's essence without providing any new information, so the sentence does not 'earn its place' by adding value. While brevity is good, this is too terse to be helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with two parameters and no output schema, the description is incomplete. It does not mention the return value, any confirmation, or how it differs from similar tools like removing from every campaign. An agent cannot fully assess consequences or select this over siblings without additional information, and the description provides no such context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning both parameters are documented as 'Contact Id' and 'Campaigns Id'. The tool description itself adds no additional meaning about parameters, such as format, required format, or relationships. Since the schema already handles the semantics, the description is not required to compensate, and the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove Contact From Campaign' clearly states the action and resource, so an agent knows it removes a contact from a campaign. However, it is essentially a restatement of the tool name without any additional context or nuances, and it does not differentiate this tool from similar siblings like 'contacts_remove_contact_from_every_campaign' or 'contacts_add_contact_to_campaign' beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description gives no context on prerequisites, scope, or scenarios where this tool is appropriate. With siblings that remove a contact from every campaign or add contacts to campaigns, the lack of any usage direction leaves an agent guessing about which operation fits a given task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already declare. It does not mention that the tool modifies conversation fields, that it is idempotent, or any side effects. With annotations present, the description still fails to add any extra context about what happens during the update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is an extremely short phrase that is under-specified. It lacks any structure, front-loading of key information, or explanation. While concise, it does not earn its place because it offers no useful content beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has five parameters, one required, and no output schema, the description is grossly insufficient. An agent would have no idea what fields can be updated, what the effects are, or what the response looks like. The minimal description does not cover the necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 80%, which is high, so the baseline is 3 even if the description adds no parameter details. The description does not elaborate on any parameter meaning, but the schema already describes most parameters. No additional value is provided, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Conversation' only restates the tool's name and basic action. It does not specify what aspects of a conversation can be updated (e.g., starred, unreadCount, feedback) nor does it distinguish this tool from other 'update' tools like contacts_update_contact. It fails to convey the specific scope of the update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus other conversation tools such as conversations_create_conversation or conversations_update_message_status. No conditions, prerequisites, or alternative references are provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds no behavioral context, such as warning that updating options replaces the existing array (a nuance only present in the schema). It does not contradict annotations but provides zero value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief, but it is not good conciseness—it is under-specification. It lacks any structural detail or front-loading of critical information that an agent would need to decide whether to call this tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich annotations and schema, the description is incomplete. For an update operation with 9 parameters, it does not explain the effect of the update (e.g., options replacement), nor any return value or side effects. The schema covers some, but the description fails to synthesize usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (89%), so the schema documents most parameters. The description provides no additional information about parameters, but the baseline of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Custom Field By Id' is essentially a tautology of the tool name and title. It states a verb and resource but adds no specificity about what fields can be updated or how it differs from sibling tools like custom_fields_create_custom_field or custom_fields_get_custom_field_by_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or exclusions, leaving the agent to infer usage from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds no further behavioral context—it does not disclose what creating a tag entails, whether it can overwrite existing tags, or any permission requirements. It simply repeats the intent without elaboration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), which is efficient, but it is under-specified and fails to include necessary context. It is not front-loaded with useful information because there is no information beyond the verb and object. It is short but not appropriately sized for an effective tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that creates a tag, the description is completely inadequate. It does not explain that it creates a tag for a location, that the name is required, or that locationId defaults to the location context. With no output schema and only minimal parameter docs, the agent is left without any situational understanding of what the tool accomplishes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the input schema. The description adds no additional meaning to either 'name' or 'locationId', so the baseline score of 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Tag' directly restates the tool's name (locations_create_tag), which is a tautology. It does state the verb and object, but adds no elaboration on the scope (e.g., that it creates a location tag) or how it differs from sibling tag operations like locations_update_tag or locations_delete_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No information is provided about when to use this tool versus alternatives. There is no mention of prerequisites, contexts, or exclusions. The description gives the agent zero guidance on selecting this tool over other create or tag-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description only repeats the destructive nature. It does not elaborate on side effects (e.g., whether associated records are affected), reversibility, or idempotency behavior beyond what annotations imply. No additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While extremely short, the description is under-specified. It conveys no structure or key details, making it an ineffective summary. Conciseness without substance is not valuable; it fails to inform the agent about any operational nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description is inadequate. It omits effects on related data, error behavior, and any caveats. The agent has no information beyond the annotation that it is destructive, which is insufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (tagId and locationId) are already documented in the input schema. The description adds no further meaning about parameter usage, defaults, or relationships, 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.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete tag' is a tautology of the tool name and lacks specificity about what kind of tag is being deleted. It does not mention location tags, although the tool name includes 'locations'. This makes it ambiguous and fails to clarify the exact scope of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, no context about prerequisites, and no mention of alternative tools. The description offers no help in deciding whether to use this delete operation versus any other delete or update tool for tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. However, it adds no additional behavioral context, such as what the response contains (custom field definitions, values, etc.), whether results are paginated, or how the model parameter affects the output beyond what the schema states. The description adds essentially nothing 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just three words, which is concise but severely under-specified. It's only a title-like phrase, not a proper description. Under-specification is not true conciseness; the structure is essentially absent, providing no useful information in an organized manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a terse description, the tool lacks essential context. An agent cannot determine what the custom fields represent, how they are organized, whether the response is a list or a single object, or any edge cases like default location handling beyond the schema note. The tool's role in the larger locations domain is unclear, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for both parameters: 'model' explains it selects contact, opportunity, or all, and 'locationId' notes default behavior. With 100% schema description coverage, the baseline is 3 even without additional parameter detail in the description. The description itself offers no extra semantics, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Custom Fields' states a verb and resource but is extremely vague. It does not specify that these are location-scoped custom fields, nor does it distinguish from sibling tools like locations_get_custom_field (singular) or custom_fields_get_custom_fields_by_object_key. The schema hints at contact/opportunity models, but the description alone leaves the agent guessing about what exactly is being retrieved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. For example, it doesn't clarify when to prefer this over locations_get_custom_field or custom_fields_get_custom_fields_by_object_key, nor does it mention whether this is the right tool for a specific scenario (e.g., retrieving all custom fields for a location). The agent is left to infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as destructive and idempotent. The description adds no additional behavioral context such as permanence, side effects, or required permissions. It repeats the destructive nature without providing new information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified, consisting only of 'Delete Record'. While concise, it lacks substance and fails to provide useful information for agent decision-making.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description omits any caution about irreversibility, expected outcomes, or error handling. With no output schema, it doesn't describe return values or success criteria, making the tool underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides detailed descriptions for both parameters (id and schemaKey), covering 100% of the schema. The description adds nothing beyond what's already in the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Record' is a minimal restatement of the tool name. It does not specify which record type or how it differs from other delete tools in the sibling list, such as objects_delete_custom_object (though that one isn't present, but other deletes exist). It lacks specificity to guide an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other delete tools or how to obtain the required parameters. The schema descriptions help for parameters, but the description offers no contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint:false, covering safety. The description adds no extra behavioral context, such as what is returned, error conditions, or authentication requirements. It does not contradict annotations, but it provides no value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, 'Fetch Coupon'. While concise, it is under-specified and lacks any structure or elaboration. It does not earn its place because it omits critical details like required parameters or return behavior, making it more of a placeholder than a useful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 should explain what the tool returns or any notable effects. It does not. It also fails to clarify how to use the required parameters (id and code) together. The annotations cover safety, but the description is incomplete for a 4-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all parameters (id, code, altId, altType), so the description does not need to add parameter details. It adds no additional meaning or clarification, which is acceptable given the high schema coverage, but it does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch Coupon' states a specific verb and resource, distinguishing it from the sibling list tool 'payments_list_coupons' by singular/plural. However, it is vague and does not clarify whether it fetches by id, code, or both, leaving the operation ambiguous despite the schema showing required 'id' and 'code'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description offers no context about when to prefer this over 'payments_list_coupons' or how it relates to other coupon operations. No exclusions or alternative conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) and non-destructive intent (destructiveHint=false). The description simply restates the action without disclosing side effects, prerequisites, or what happens to the product's store status. It adds no behavioral context beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single concise sentence, but it is extremely terse and lacks any formatting or structure to separate purpose from context. While efficient, it fails to convey useful information beyond the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, 2 enums, and no output schema, the description is severely lacking. It does not explain the purpose of the storeId, productIds, or how 'include/exclude' affects the store. The tool is under-specified 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description does not add meaning beyond the schema's parameter descriptions; it merely echoes the action in the 'action' parameter. No additional value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the core action (include/exclude) and the resource (product in store), but it lacks specificity about what 'store status' means and does not clearly differentiate from other product tools. The verb and resource are present, but the purpose is partially vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not explain conditions for include vs exclude, any dependencies, or what distinguishes it from other product management tools. There is zero contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. However, the description adds no additional behavioral context such as pagination behavior, rate limits, authentication needs, or response characteristics. It does not contradict annotations, but it also contributes nothing beyond what is already structured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('List templates'), which is not conciseness but under-specification. It lacks critical details that an agent needs, making it too terse to be useful. A concise description would be efficient while still conveying scope and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters and no output schema, the description is severely incomplete. It does not explain what the response looks like, when to use parameters like 'type' or 'isPublicDocument', or how the tool fits into the overall workflow. The agent has to rely entirely on schema names and sibling hints, which is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 9 parameters have descriptions), so the baseline is 3. The description does not add any parameter explanation or enrich the schema's minimal descriptions (e.g., 'Skip', 'Limit', 'Template Name'). It fails to provide additional meaning beyond the schema, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List templates' is a generic, bare statement that barely goes beyond the tool name. It identifies a verb and a resource but does not specify what kind of templates (e.g., proposal, estimate, content library) or how it differs from the sibling 'proposals_list_documents_contracts'. The purpose is vague and offers no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like proposals_list_documents_contracts or proposals_send_documents_contracts_template. No context is provided about filtering, scope, or prerequisites, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as return format, pagination behavior, or default values. It provides no insight beyond what the annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of only two words. While it is front-loaded and free of fluff, it is so terse that it offers no structural information. It is appropriately sized for a minimal mention but lacks any helpful organization or emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, 5 required, nested objects, and no output schema, the description is completely inadequate. It does not explain what constitutes a post, how to use filters like type or accounts, or what the required parameters mean. The agent is left to infer everything from the schema, which is insufficient for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 78%, so most parameters are documented in the schema. The description itself adds no extra meaning to parameters. Given the high schema coverage, the baseline of 3 is appropriate; the description does not compensate for the uncovered parameters but also does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('Get posts') which clearly indicates the action, but it does not differentiate from sibling tools like 'social_media_posting_get_post' (singular) or provide any detail about the type or scope of posts. It is minimally clear but lacks specificity to distinguish it from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention filtering options, pagination, or any conditions that would lead an agent to select this tool over others. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already specify readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. However, the description adds no behavioral insight beyond what annotations provide—no mention of return data, error cases, or any operational nuance. It contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (3 words) but fails to 'earn its place' because it simply repeats the tool name. It is not appropriately sized—it is under-specified and lacks any meaningful content. Prefrontal structure is absent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation, the description is incomplete. It doesn't explain what the response contains, that both shippingZoneId and shippingRateId are required (though schema shows this), or any error handling. There is no output schema, so the description should provide more context, but it doesn't.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (shippingRateId, shippingZoneId, altId, altType) documented. The description does not add any parameter context, so baseline 3 applies. Since it doesn't compensate for any gaps, no higher score is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Shipping Rate' is essentially a restatement of the tool name 'store_get_shipping_rates'. It does not elaborate on the specific resource being fetched or differentiate from sibling tools like store_list_shipping_rates. It is nearly tautological, providing no additional clarity beyond what the name already conveys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it fetches a single rate by ID, or contrast with listing rates, or any prerequisites. The agent is left without context on appropriate invocation scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond this—such as what the returned action object contains, whether it can return null for missing IDs, or how the default locationId affects results. With no additional context, the description fails to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words, which is under-specification rather than effective conciseness. It does not front-load any informative content beyond the name, and it omits crucial details such as what the tool actually returns or how it behaves. A concise description should pack more meaning into few words, not merely restate the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description should explain what the response contains. It also lacks an explanation of the 'Agent Action' concept and how locationId defaulting works. The description is incomplete for a tool that retrieves a specific entity; an agent would need to look elsewhere to understand what it is getting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—both actionId and locationId have descriptive text in the schema. The description itself adds no further parameter meaning, so it meets the baseline for high coverage. No extra detail like parameter formats or relationships is provided, but the schema already handles semantics adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Agent Action' is vague and barely expands on the tool name. It does not specify what an 'Agent Action' is, nor does it distinguish this tool from similar ones like conversation_ai_get_action_by_id or voice_ai_get_agent. A clear statement of what the action represents and the resource being retrieved is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any conditions, prerequisites, or exclusions. The agent is left to infer usage solely from the name and parameters, which is insufficient given the many similar 'get' tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), destructiveHint=false (not destructive), and idempotentHint=true (idempotent). The description adds no behavioral context beyond these hints, such as what fields are updated, whether it is a full replacement or partial update, or any side effects. Since annotations exist, the bar is lower, but the description still fails to add any meaningful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short (four words), this is under-specification rather than effective conciseness. It lacks any structure or front-loaded information that would help an agent understand the tool. It does not earn its place beyond echoing the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a complex input schema and missing output schema, the description is inadequate. It does not explain the overall purpose, the effect of updating an action, or any contextual information about when this operation is needed. An agent would need to rely entirely on the parameter descriptions, which do not provide the high-level purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all six parameters, with detailed descriptions for each property including nested object fields. The tool description adds no parameter-specific information, but because the schema already provides comprehensive semantics, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Agent Action' is essentially a restatement of the tool name 'voice_ai_update_action'. It does not add specificity about what updating an action entails or what distinguishes it from other action-related tools like create or delete. It provides minimal value beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool over alternatives. It does not mention scenarios where an update is appropriate, whether it should be used for partial modifications, or any prerequisites. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate these. However, it adds no context about what happens to the ad set, whether deletion is permanent, or any side effects. The description is consistent with annotations but contributes no extra behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words and under-specified rather than concise. It lacks structure and substance, similar to a tautological restatement of the tool name. It does not provide enough information to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete operation with required parameters and no output schema, the description is severely incomplete. It omits any details about what is required, consequences, or how to verify deletion. An agent would need to rely entirely on the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (locationId has a description, adsetId does not). The tool description does not mention any parameters, so it fails to compensate for the missing adsetId documentation. It adds no semantic insight beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'delete' and the resource 'ad set', which is clear and matches the tool name. However, it does not differentiate from sibling delete tools like ad_manager_fb_delete_ad or ad_manager_fb_delete_campaign; it merely restates the name without added specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as delete_campaign or delete_ad. The description provides no context about prerequisites, conditions, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint. The description adds no behavioral context beyond these flags—it does not explain output format, pagination, potential filters, or any side effects. With annotations covering the safety profile, the description's lack of additional info yields a low score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two words—which is front-loaded and lacks superfluous text. However, it is under-specified to the point of being uninformative. It is not 'appropriately sized' because crucial information about filters and behavior is omitted, making the brevity a drawback rather than a strength.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters and no output schema, the description fails to convey even basic expectations. It does not mention what the response contains, how status filters results, or what happens when locationId is omitted. The agent cannot predict the tool's behavior from this description, so it is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: only locationId has a description, while status has none. The description 'Get Campaigns' adds no elaboration on either parameter, failing to explain what status values mean or how locationId interacts. It does not compensate for the incomplete schema, leaving parameter semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Get') and resource ('Campaigns'), making the tool's purpose immediately understandable. However, it does not specify the scope or type of campaigns (e.g., all campaigns for a location, campaigns from a specific platform), and it does not differentiate from sibling tools like ad_manager_fb_get_campaign or ad_manager_google_get_campaign_by_id. Thus, it is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any filtering conditions, prerequisites, or scenarios where a different tool would be more appropriate. There is no indication of exclusions or preferred usage context, leaving the agent without direction for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, indicating it is a mutation but not destructive. The description adds no behavioral context beyond that—it doesn't mention effects, idempotency, reversibility, or permissions. It is minimal and adds no value over 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two words—but it is under-specified. It lacks the structure needed to convey the intended action and context. It is not merely concise; it is incomplete, making it ineffective for agent selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description should at least define the parameters and expected behavior. It provides almost no context about what a 'follower' is, how the operation works, or what outcome to expect. The tool is poorly documented even for a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover only 'contactId' with 'Contact Id'; 'followers' has no description. The description 'Add Followers' does not clarify what 'followers' means (e.g., IDs, emails, usernames) or how they relate to the contact. It fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add Followers' provides a verb and an object but is ambiguous about the context—it does not explicitly state that it adds followers to a specific contact. The tool name contains 'contact' and the schema has a contactId, but the description alone is vague and does not distinguish this from other add operations. It is not a tautology, but it lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, such as contacts_remove_followers_contact or other contacts_add_* tools. There is no mention of prerequisites, exclusions, or scenarios. No usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no additional behavioral context, such as return format, pagination, or any side effects, but since annotations cover the safety profile, it meets the baseline expectation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (a single phrase), which is not verbose but also lacks structure and front-loading of key information. It is short enough to be focused, but it omits necessary details, so it balances between being appropriately brief and under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a very thin description, an agent cannot determine what 'generation details' are returned, what the 'source' enum means, or how to correctly invoke the tool. For a 2-parameter tool with an enum, this is insufficient context to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (only messageId has a trivial 'Message Id' description; source has no description). The tool description does not attempt to clarify parameter meanings or the distinction between source values. Given the low coverage, the description should compensate but fails to, leaving the source parameter ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the generation details' essentially restates the tool name without adding specificity. It does not explain what 'generation details' refers to or how it differs from other conversation_ai_get_* tools like conversation_ai_get_action_by_id or conversation_ai_get_agent. The purpose is vague and barely goes beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor how to choose between the 'conversation' and 'workflow' values for the source parameter. The description gives no context about the input selection or any prerequisites, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. However, the description adds no behavioral context beyond that—it does not disclose what the response contains, whether pagination is used, or any side effects. Given the annotations, this is a neutral but unhelpful description, scoring a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence and is front-loaded with the action, but it is under-specified. It is concise in length but lacks substance, making it only minimally acceptable. It does not waste words but also does not convey useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the tool returns. It does not. It also fails to clarify what 'custom subtypes' are or in what domain they apply. An agent would be unsure of the expected result or the scope of the operation, making it incomplete for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single optional parameter locationId that has a clear description ('Location Id Defaults to GHL_LOCATION_ID when omitted'). The tool description adds no additional meaning about the parameter, so it earns the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get All Custom Subtypes' is essentially a tautology of the tool name. It states a verb and resource but adds no information about what a 'custom subtype' is or that it relates to conversations. It fails to distinguish from sibling tools like conversations_get_conversation or conversations_get_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. Sibling tools such as conversations_create_custom_subtype and conversations_update_custom_subtype exist, but there is no mention of how this listing tool fits into the workflow or when it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only (readOnlyHint false) and not destructive (destructiveHint false), but the description adds no behavioral details such as whether it overwrites existing courses, requires external systems (openWorldHint true), or handles bulk operations. The description is redundant with the name and lacks any extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (two words), which is concise but under-specified. It lacks any structure or elaboration that would help an agent understand the operation. While it front-loads the verb, it fails to provide necessary context, making it more of an under-specification than a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters including a required complex array and produces no output schema, the description is woefully incomplete. An agent has no indication of the expected product structure, the purpose of userId, or what the tool returns. This makes the tool effectively unusable without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes only locationId (33% coverage), leaving the required 'products' array and 'userId' undefined. The description offers no explanation for these parameters, their structure, or expected values. With low schema coverage, the description should compensate but does not, making it impossible for an agent to construct valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Import Courses' states a clear verb and resource, indicating the action is to import course data. It is concise and unambiguous, though it does not elaborate on the source or format. There are no conflicting sibling tools with a similar name, so it stands out sufficiently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, what prerequisites exist, or how it differs from alternatives. The description provides zero context about typical use cases or when not to use it. Without any usage instructions, an agent is left to infer its applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-destructive, non-idempotent, open-world behavior. The description adds no additional behavioral context beyond the purpose itself, such as side effects, permission requirements, or error conditions. With annotations present, a baseline of 3 could be considered, but the description contributes nothing extra, so 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (6 words), making it concise, but it is under-specified. It lacks any structural detail that would help an agent understand the tool's capabilities. It is closer to a label than a helpful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, 2 required, no output schema, and minimal parameter descriptions, the description is severely incomplete. An agent would not know what inputs to provide, what behaviors to expect, or how to handle errors. The description fails to provide essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 8% (only locationId has a description). The description does not explain any parameters, nor does it mention which fields are required or how they relate to template creation. Given the low schema coverage, the description must compensate, but it fails entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new template' clearly states a specific action (create) on a resource (template). It is distinct from sibling tools like emails_update_template, emails_delete_template, etc. However, it does not specify that it is an email template explicitly, though the tool name and context make that clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description offers no mention of required parameters (type, importProvider), no prerequisites, and no exclusions. The agent must infer usage solely from the tool name, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent. The description adds no additional behavioral context, such as whether the update is partial or full, what happens to unspecified fields, or any side effects. There is no contradiction with annotations, but no extra transparency beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (three words), but it is under-specified rather than concise. It does not earn its place as it merely restates the tool name and adds no informational value. A good description should provide more substance while staying efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nested objects, enum, no output schema), a one-line description is grossly insufficient. It does not explain update semantics, required fields, or any operational details. The agent would have to rely entirely on the schema and hope for clarity, which is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, leaving most parameters undocumented. The description does not explain any parameter meanings or provide context for the required fields (templateId, updatedBy, dnd, html, editorType). With such low coverage, the description fails to compensate, offering zero parameter clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'update' and the resource 'template', making the core purpose clear. However, it does not explicitly distinguish from sibling tools like emails_create_template or emails_delete_template; the differentiation relies on the tool name itself rather than the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention conditions like 'when a template already exists' or contrast with create/delete/fetch operations. The description is a bare statement with no contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the description is relieved of repeating those. However, the description adds no extra behavioral context: it doesn't explain what data is returned, any side effects, or anything beyond what the annotations convey. With annotations present, the bar is lower, but the description still fails to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is simply 'Get Custom Values'—brief and without fluff, which is concise. However, it is under-specified to the point that it does not earn its place; it fails to convey the tool's purpose clearly. Conciseness should be paired with informativeness, which is lacking here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one optional parameter and no output schema, a complete description should at least clarify what 'custom values' are and how they relate to the location. The current description leaves this ambiguous, especially with the singular sibling tool. The annotations cover safety, but the description is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter 'locationId' with its default behavior, achieving 100% schema description coverage. The description itself adds no additional meaning about the parameter. Since the schema carries the weight, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('Get') and a resource ('Custom Values'), making the basic intent clear. However, it is vague about what 'Custom Values' refers to in this context, and there is a sibling tool 'locations_get_custom_value' (singular) that could easily be confused with this one. The description does not differentiate between the two, so the purpose is only partially clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any context, exclusions, or alternative tools. An agent has no basis for choosing this over the singular 'locations_get_custom_value' or other related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) already indicate a safe read operation. The description adds no additional behavioral context, such as pagination behavior, searchAfter semantics, or result structure. It does not contradict annotations, but it provides no extra value 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but under-specified. It lacks necessary content to be useful; it is not 'appropriately sized' because it does not convey the required information for a tool with 6 parameters. Front-loading is present but empty of substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (5 required), no output schema, and complex search behavior (pagination, searchAfter), the description is severely incomplete. It does not explain the search mechanism, the meaning of searchAfter, or how results are paginated. This is inadequate 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83% (5 of 6 parameters have descriptions), so baseline is 3. The description itself adds no parameter insights beyond the schema. The schema descriptions are mostly terse ('Page', 'Page Limit'), but the query parameter has a helpful example. The tool description does not compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Object Records' states a clear verb and resource, but it is generic and does not clarify what 'Object Records' refers to (custom objects) nor differentiate it from sibling search tools like contacts_search_contacts_advanced or opportunities_search_opportunity. It is not a tautology, but it lacks specificity to distinguish it from other search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when to prefer this over objects_get_record_by_id or other search tools. The schema hints at custom objects via schemaKey, but the description itself offers no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description does not add any behavioral context beyond the name, such as what gets mutated, authentication needs, or side effects. Given the annotations present, the description contributes minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two words, but it is under-specified rather than efficiently structured. It omits critical information that an agent would need, making the brevity a deficiency rather than a benefit.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters, including nested objects and no output schema, the description is grossly incomplete. It provides no information about required fields, behavior, return values, or usage context, making it nearly useless for an agent attempting to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 14 parameters, so the schema fully documents parameter meaning. The description itself provides no parameter information, which is acceptable since the schema carries the weight. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Coupon' clearly identifies the verb (update) and resource (coupon), which distinguishes it from other tools like payments_create_coupon. However, it lacks any specifics about what can be updated or any additional context, so it is only minimally useful beyond the tool name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like payments_create_coupon or payments_delete_coupon. It does not state prerequisites, context, or when this update is appropriate, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=false and destructiveHint=false, indicating a write operation. The description only says 'Update' which does not add meaningful behavioral context beyond the schema. It does not disclose what happens to existing reviews, whether it appends or replaces, or any side effects. Given the annotations already cover the basic write nature, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, consisting of a single phrase. While it is concise and front-loaded in the sense of being immediately readable, it is under-specified and fails to convey essential operation details. It does not waste words, but it also does not provide enough substance to be considered well-structured for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, 2 required, nested objects, and no output schema. The description provides no context about the expected structure of the reviews array, the meaning of the status object, or any constraints (e.g., allowed status values). Without this information, an agent may struggle to construct a valid request. The description is clearly incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 4 parameters, including 'reviews' and 'status', with 100% coverage. The tool description does not add any additional semantic meaning to the parameters, but since the schema is rich enough, the baseline score of 3 applies. The status object and reviews array are not explained further, but the agent can rely on schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update' and the resource 'Product Reviews', but it is vague and does not clarify the bulk nature of the operation. Given the sibling 'products_update_product_review' (singular), an agent cannot differentiate between bulk and single update from the description alone. The purpose is clear enough but lacks specificity and 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling tools. There is no mention of bulk vs. single update, no prerequisites, and no indication that this is the appropriate choice for batch operations. An agent is left to infer usage from the name, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. However, the description adds no behavioral context beyond the annotations. It does not mention pagination defaults, the meaning of the search parameter, or what fields are returned. For a read tool, this is a minimal but incomplete disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just two words, which is efficient, but it sacrifices clarity and completeness. There is no wasted text, but it fails to include critical information about the tool's operation. A balanced description would be slightly longer to cover key usage points while remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and the tool has 5 optional parameters, the description should explain what the list returns (e.g., inventory items with quantities) and any default behavior (e.g., default pagination size). The description is too sparse to give an agent enough context to call the tool correctly. Annotations cover safety, but not the functional details, so the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (altId, limit, offset, search, altType) have descriptions in the schema. The tool description adds no extra meaning about how these parameters interact or affect results. Since the schema already explains each parameter clearly, the baseline of 3 is appropriate; the description neither enhances nor detracts from parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Inventory' clearly states a verb ('list') and a resource ('inventory'), but it is vague about what inventory items are returned or what 'inventory' means in this context. It does not distinguish itself from sibling tools like products_list_prices_for_product or products_get_product_by_id, which are also list/read operations. A more specific description like 'List inventory records for products with optional search and pagination' would clarify its exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or any exclusions. It does not mention that it is a read-only listing operation, nor does it clarify whether it lists all inventory or filters by product. Without any usage direction, an agent cannot determine when this tool is the right choice among the many similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the auth requirement (agency-level token), which is useful, but it omits side effects, reversibility, and how existing SaaS settings are affected. With minimal annotations (no read-only, destructive, or idempotent hints), the description carries the burden and fails to disclose behavioral outcomes beyond the token note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but under-specified. It front-loads the token requirement but omits critical operational details. It is not efficient conciseness; it is the absence of necessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with a nested payload (actionPayload), no output schema, and sparse annotations. The description does not explain the actionPayload structure, the meaning of isSaaSV2, or the deprecation status (only the name indicates it). An agent cannot correctly call this tool without external knowledge, making it highly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters, so the baseline is 3. The tool description adds no additional meaning beyond what the schema already provides, and the schema descriptions themselves are generic. It neither improves nor worsens the agent's understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb and resource ('Bulk Enable SaaS') which is clear enough but vague about what 'enable' actually does. It does not differentiate from the non-deprecated sibling saas_api_bulk_enable_saas, so an agent cannot tell if there are behavioral differences or which to prefer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the token requirement ('requires an agency-level token, not a location PIT'), which is a prerequisite but not a when-to-use instruction. It does not mention when to use this tool versus alternatives like the non-deprecated version or single-location enable, nor any exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds no behavioral context beyond the word 'attach', such as side effects, reversibility, or whether existing attachments are replaced. No new information is provided beyond what the annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one phrase), but this is under-specification rather than effective conciseness. It lacks structure and fails to front-load useful detail. While not verbose, it does not earn its place because it adds minimal value beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given 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, and a clear need to differentiate from sibling attach tools), a one-line description is wholly inadequate. It provides no context on workflow, parameter relationships, or expected behavior, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38%, and the description does not explain any parameter. Many fields (urn, name, type, avatar, originId) lack descriptions in both the schema and the tool description. The description adds no semantic meaning to any parameter, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Attach linkedin pages and profile' clearly states a specific verb (attach) and resource (LinkedIn pages and profile), and the tool name itself distinguishes it from sibling tools for other platforms. It is not a tautology and conveys the basic action, though it leaves the broader context (e.g., attaching to what) implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool over the sibling 'attach' tools (e.g., attach_facebook_page_group, attach_instagram_page_group), nor does it mention prerequisites or a typical workflow. The agent is left to infer intent from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds no behavioral context beyond what the name implies—it does not explain mutation semantics, permission requirements, or side effects. No contradiction exists, but no additional transparency is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two words is technically concise but it is under-specification rather than efficient conciseness. The description does not front-load any useful information and fails to earn its place by conveying any operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 16 parameters, nested objects (permissions, twilioPhone), and a large enum list for scopes, the description is completely inadequate. An agent cannot reliably construct a correct request without consulting the schema in full, and even then, ambiguity around behaviors like scopes replacement semantics (partially covered in schema) remains. No output schema exists, so the description also fails to hint at return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only 44% parameter description coverage, leaving many parameters (e.g., role, type, phone, firstName, lastName) undocumented. The description 'Update User' provides zero insight into parameter meanings or usage, and does not compensate for the schema gaps. The agent is left to infer semantics from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update User' clearly identifies the action (update) and the resource (user), which is a specific verb+resource. However, it does not distinguish itself from sibling tools like users_create_user or users_delete_user, and lacks any additional context about what 'update' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., users_create_user, users_delete_user). The description does not mention any prerequisites, exclusions, or conditions that would help an agent decide to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, implying a side-effecting, non-read operation. The description adds no behavioral context beyond the bare statement, such as potential side effects, required permissions, or response format. It neither contradicts nor enriches the annotation profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is ultra-concise (one short phrase) but is under-specified rather than appropriately concise. It does not 'earn its place' because it provides almost no information beyond the name. There is no front-loading of critical details, and it fails to structure any useful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with a nested actionParameters object and eight possible actionType values, yet the description provides no overview. It does not explain what an Agent Action is, which action types exist, how parameters vary by type, or what the response looks like. The schema offers detail, but the description leaves the agent without high-level context needed to decide when and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning every parameter has a description in the schema, including the complex actionParameters object. The tool description adds no parameter info, but the schema already documents all fields and the enum for actionType. Baseline 3 is appropriate given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Agent Action' states a verb and resource, making the core purpose clear. However, it is extremely generic and does not distinguish this from sibling tools like voice_ai_create_agent or voice_ai_update_action. It lacks any specificity about what an 'Agent Action' entails beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives, mention prerequisites, or note any context such as requiring an existing agent. An agent would have to infer usage solely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context, such as that this returns a list, supports pagination, or requires pre-existing integration – leaving the agent without insight into what the call actually does beyond a generic fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no unnecessary words, making it efficient. However, it is so minimal that it sacrifices informative value, though it remains appropriately short for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, pagination controls, and no output schema, the description is incomplete. It lacks any indication of return structure, usage context, or differentiation from related tools, making it harder for an agent to invoke it correctly in practice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the 5 parameters with descriptions, so the schema already documents each parameter. The description adds no extra meaning beyond what the schema provides, warranting the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get ad accounts' states a clear verb and resource, but it does not specify that it is Facebook-specific or differentiate it from the singular sibling ad_manager_fb_get_ad_account or the Google/LinkedIn equivalents. Without the tool name, the scope is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus the singular get_ad_account or other platform-specific account listers. The description does not mention key features like pagination or filtering options, leaving the agent without context on how to choose the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which convey the safety profile. However, the description adds no additional behavioral information such as what data is returned, whether pagination exists, or any request-specific constraints. It solely relies on annotations, providing no extra value beyond the 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but under-specified. A single phrase may be concise, but it does not front-load important information or structure details. It fails to earn its place by providing insufficient detail for an agent to act confidently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool of this complexity. It does not mention what the report contains, whether date ranges are required (though schema indicates required params), or any nuances. Given no output schema, the lack of clarity about the return format is a significant gap. An agent would need to infer from the name and schema alone, which is not ideal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no parameter-level meaning beyond that, which is acceptable given the baseline of 3 when the schema is complete. No additional clarification is needed from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'get' and the resource 'campaign reporting', which is clear at a basic level. However, it does not specify what 'reporting' includes (metrics, date ranges, scope) and does not differentiate from sibling tools like ad_manager_fb_get_reporting or ad_manager_fb_get_reporting_list. It is not a tautology but is vague enough to leave the agent guessing about the exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or comparisons to siblings. The agent is left without any context to choose the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no behavioral traits beyond the fact that it pauses an ad set, which is inherent to the name. While annotations indicate it is not read-only (readOnlyHint=false) and not destructive, the description adds no detail on side effects, permissions, or impact on related entities, leaving the agent with insufficient insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is under-specified rather than concise. It lacks any structural elements such as context, examples, or necessary caveats, and fails to front-load critical information an agent would need.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is severely incomplete for a mutation tool. It does not mention return values, side effects, required permissions, or how to obtain the adsetId. With no output schema and minimal annotations, the description leaves the agent without enough information to call the tool correctly and confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to the parameters. One parameter (locationId) has a schema description, but adsetId is undocumented. The description does not explain what an adsetId is or how to obtain it, and does not compensate for the 50% schema coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Pause ad set' clearly states the verb (pause) and resource (ad set), making the action unambiguous. However, it does not differentiate from sibling tools like ad_manager_fb_pause_ad or ad_manager_fb_resume_adset, relying entirely on the tool name for that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives, no prerequisites, and no context about the state changes involved. The description provides no help in selecting this tool over pause_ad, pause_campaign, or others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. However, the description adds no additional behavioral context, such as whether deletion is permanent, what side effects might occur, or whether any permissions are required. For a destructive tool, more transparency would be expected even with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words, which is structurally efficient. It is not overlong, but it is also not informative. While it is not harmful, it could be considered under-specification rather than true conciseness, though the brevity itself is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description fails to mention what the tool returns, whether the operation is reversible, or any warnings about consequences. The schema covers parameters, and annotations cover safety, but the overall context is incomplete. The description does not explain the effect of deleting a conversion or any dependencies (e.g., integration requirements).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage: both conversionId and locationId are documented with clear descriptions, including the default behavior for locationId. The description itself does not mention parameters at all, but since the schema already explains them, the baseline of 3 applies. The description adds no extra parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete conversion' clearly states the action (delete) and the resource (conversion), so an agent can infer the tool's purpose. However, it is extremely terse and does not differentiate from sibling delete tools like ad_manager_google_delete_segment or ad_manager_google_delete_ad_account, relying entirely on the tool name for context. It is not a tautology, but it adds no scope or specificity beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as ad_manager_google_upsert_conversion or ad_manager_google_get_conversions. There is no mention of prerequisites, use cases, or situations where deletion is appropriate. The agent is left to infer usage purely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, which fully covers the safety profile. The description adds no behavioral context beyond this, but it does not contradict the annotations either. Thus, a baseline score of 3 is appropriate since annotations carry the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse—just two words—but this is under-specification rather than effective conciseness. It lacks any front-loaded useful information, such as what the tool returns or how it is scoped. While there is no wasted prose, there is also no substantive content, making it too minimal to be helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 annotations and schema provide the required parameter and safety information, but the description fails to explain the operation's purpose or output. It does not state that it retrieves a single affiliate record, nor does it describe any return format. An agent must rely entirely on the name and schema, leaving gaps in understanding tool behavior and appropriate use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both affiliateId and locationId have clear descriptions in the schema. The description 'Get Affiliate' contributes nothing about parameter usage or relationships. With high schema coverage, a baseline of 3 applies, and the description does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Affiliate' states a verb and a resource, but it essentially repeats the tool name without adding any detail about what 'get' entails (e.g., retrieving a single affiliate by ID). It does not distinguish itself from sibling affiliate_manager_list_affiliates, though the name implies a singular fetch. This is minimally clear but lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like affiliate_manager_list_affiliates, no mention of prerequisites, and no context about selecting this over similar get/list tools. The description provides zero direction for an agent deciding which tool to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint: false) already establish that this is a safe, read-only operation. The description adds no extra behavioral context, such as pagination behavior, default parameter values, or any side effects. It fails to disclose anything beyond what the schema and annotations already convey, providing no incremental value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), which is efficient, but it is under-specified. It is front-loaded with the core action, yet it lacks any additional structure or context that would help an agent. Concision is good, but not at the expense of utility; the description earns its place by stating the purpose, but a slightly richer structure would improve it without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 is woefully incomplete. It does not address pagination (skip/limit), date filtering (start/end), or how to interpret status/query. The locationId parameter already notes a default in the schema, but the description itself adds no guidance. An agent cannot confidently call this tool without external knowledge, making it incomplete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 56%, meaning four of nine parameters (end, skip, limit, start) have no descriptions. The tool description does not help interpret any parameters; it is silent about skip/limit for pagination, date ranges, or the meaning of 'query'. Since coverage is not high, the description should compensate but does not, leaving crucial parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Payouts' clearly states a specific verb (list) and resource (payouts), which is unambiguous. It does not restate the full tool name verbatim, but the resource is precise enough to distinguish from sibling tools like affiliate_manager_list_commissions. However, it does not add any qualifying details (e.g., scope, filtering), so it is slightly below a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as affiliate_manager_list_commissions or affiliate_manager_list_affiliates. There is no mention of conditions, prerequisites, or contextual cues. The agent must infer usage solely from the name and schema, which is insufficient for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context such as pagination behavior, default scoping, or what the response contains. For a list operation, this is a significant omission since the schema does not describe the return format either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), which is not conciseness but under-specification. There is no structure or front-loading of key information. A minimal viable description would at least mention the primary purpose and any distinguishing features, which this lacks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters (2 required), no output schema, and a list operation that likely returns a paginated result, the description is grossly inadequate. It does not explain the response structure, pagination, or how filters like isPublished and source work. An agent would struggle to call this correctly without external knowledge. This is a list tool where completeness is critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40% (locationId and isPublished have descriptions, but limit and offset do not). The description itself adds no parameter meaning whatsoever. It does not explain any of the parameters, so the agent gets no help beyond the schema's limited annotations. Given the low coverage, the description should compensate, but it fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'List' and the resource 'Agents', which clearly indicates a read operation to retrieve a collection of agents. It is distinct from sibling tools like agent_studio_get_agent_by_id, which targets a single agent. However, it lacks any mention of filtering or scope, so it does not fully differentiate from other list-like tools in the same domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It neither says 'use this when you need all agents' nor mentions that agent_studio_get_agent_by_id is for a specific agent. There is no exclusion or comparison to sibling tools, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, which communicate the safety profile. The description adds no extra context about what happens on deletion (e.g., whether it cascades, is permanent, or affects related records). It offers zero value beyond the annotations, so it fails to 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words, which is technically concise but severely under-specified. It lacks any structure or additional informative sentences. Conciseness is not about brevity alone; it should still earn its place by conveying necessary information, which this does not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the abundance of similar delete tools in the sibling list, the description is incomplete. It does not explain what an association is, how it differs from a relation, how the associationId is obtained, or what effects the deletion has. The agent is left without essential context to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter, associationId, with no description, and schema description coverage is 0%. The tool description does not explain what associationId represents, how to obtain it, or any format constraints. With zero compensation from the description, the parameter semantics are entirely opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Association' clearly states the verb (delete) and the resource (association), making the primary action unambiguous. However, it does not differentiate from the sibling tool 'associations_delete_relation', leaving confusion about what distinguishes an association from a relation. It is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus any alternatives. There is no mention of prerequisites, exclusions, or distinguishing scenarios, such as how this differs from deleting a relation or when an association ID should be obtained. The agent gets no 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the write, idempotent, and non-destructive nature. The description adds no extra behavioral context such as side effects, permission requirements, or behavior for unspecified fields, so it provides minimal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 'Update Association By Id' — a single phrase with no extraneous words, and the core action is front-loaded. However, conciseness is achieved at the expense of essential detail, so while it scores well on brevity, it lacks substantive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters including two complex nested objects that are entirely unspecified, no output schema, and no additional context, the description is severely incomplete. An agent cannot reliably construct a request without knowing the expected structure of the label objects or how to obtain the associationId, making the tool nearly unusable without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning or structure of associationId, firstObjectLabel, or secondObjectLabel. The two object parameters are open-ended (additionalProperties with no schema), so an agent has no guidance on what fields to include, making correct invocation highly problematic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Association By Id' clearly states a specific verb (update) and resource (association) with an identifier, distinguishing it from sibling tools like create, get, or delete. However, it does not specify which fields of the association are updatable beyond the label objects, which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as associations_create_association or associations_get_association_by_id. The description does not mention exclusions, prerequisites, or specific scenarios, leaving the agent to infer when an update is appropriate from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=true, but the description adds no behavioral context beyond the generic 'Update'. It fails to disclose side effects, permission requirements, or whether updating triggers related changes (e.g., publishing workflows). With openWorldHint true, the description should clarify what 'open world' behavior might occur, but it remains silent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal (two words), but this is under-specification rather than effective conciseness. It lacks structure, no examples, no precedence of important information. While short, it does not earn its place by communicating anything beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters, 12 required, and no output schema, this description is grossly incomplete. It provides no mention of how to obtain required IDs (except those few in schema), no error handling notes, no format expectations (e.g., ISO timestamps), and no guidance on partial updates vs full replacement. An agent attempting to use this tool would face significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%, and the description provides no parameter clarification whatsoever. While some schema properties have helpful descriptions (e.g., author and categories mention how to obtain IDs), the description itself adds zero value in guiding parameter usage, leaving many required fields (title, rawHTML, status, etc.) unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Blog Post' clearly states the verb and resource, making its basic purpose unambiguous. It distinguishes from siblings like blogs_create_blog_post and blogs_get_blog_post through the 'Update' action, though it lacks any detail about which aspects of the post can be modified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, such as ensuring the post exists, nor does it contrast with create or delete operations. An agent must infer usage entirely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. However, it adds no extra behavioral context such as return format, pagination semantics, or that it returns a list. The description is essentially a paraphrase of the tool name and provides no incremental transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase 'Get Businesses by Location' that essentially restates the tool name. While it is concise, it fails to provide additional useful information, so the brevity is not warranted—it is under-specification rather than effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and several closely related siblings, the description is severely incomplete. It lacks any mention of return value, pagination controls, default limits, or how it differs from 'businesses_get_business'. An agent would have to guess many aspects of how to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%)—only locationId has a description. The tool description does not explain the skip and limit parameters at all, leaving their purpose and use ambiguous. It only mentions 'location', which aligns with locationId, but provides no details on pagination or required versus optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Get' and the resource 'Businesses' with a location filter, which clearly indicates a retrieval operation. It is distinguishable from the sibling 'businesses_get_business' which likely gets a single business, though it does not explicitly point to that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus other business-related tools, nor does it mention pagination behavior, default limits, or any context that would help an agent decide to call it. The description is purely declarative without any usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, covering safety. However, the description adds no behavioral context such as return format, whether a list is returned, or how blocked slots are defined. It contributes nothing 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which is concise but under-specified. It does not earn its place by adding value; it simply restates the name. A phrase this brief cannot convey necessary usage or semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description is grossly incomplete. It doesn't explain what a blocked slot is, which of the owner parameters to provide, or what the response looks like. Even with schema descriptions, the tool lacks essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no extra meaning to parameters; it merely repeats the tool name. Parameters like userId, groupId, calendarId have terse schema descriptions but no additional context from the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Blocked Slots' states a verb and resource but is vague. It doesn't define what a blocked slot is or differentiate from the similar sibling calendars_get_slots. It's barely more than the tool name, lacking domain context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios, exclusions, or how it compares to calendars_get_slots. The description leaves the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no additional behavioral context such as what happens if the resource does not exist, whether it returns null, or any special conditions. With annotations covering the core safety aspects, the description contributes nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words: 'Get Calendar Resource'. While it is undeniably concise, it is under-specified rather than efficiently structured. It merely restates the tool's name without adding any useful content, so it does not earn its place as a meaningful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two required parameters, but the description fails to clarify what the response will contain (there is no output schema). An agent calling this tool would not know if it returns details about the resource, a confirmation, or an error. Given the lack of output schema and the minimal description, more explanation is needed for the agent to call it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters 'id' and 'resourceType' are already fully documented in the schema. The description adds no extra meaning about how the parameters interact or what values are acceptable. Since the schema already carries the full weight, 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.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and object: 'Get Calendar Resource'. However, it does not specify that this retrieves a single resource by ID, nor does it distinguish itself from the sibling 'calendars_fetch_calendar_resources' which likely lists resources. The description is not a complete tautology (it adds the object 'Calendar Resource'), but it is vague and fails to differentiate among the many calendar-related get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention that it retrieves a single resource by ID while 'calendars_fetch_calendar_resources' retrieves a list, nor any indication of common use cases. The absence of any direction leaves the agent to infer usage from the parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnlyHint false), idempotent, and non-destructive. The description adds no behavioral nuance beyond those hints—it does not mention side effects, permission requirements, or what happens to unspecified fields. Since it neither contradicts nor enriches the annotations, it offers minimal transparency beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two words, which is under-specification rather than effective conciseness. While brevity is valued, a tool with 52 parameters and significant complexity needs at least a sentence describing the update scope or key fields. The description fails to provide any structural cues, making it less like a helpful summary and more like a placeholder.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (52 params, nested objects, enums) and the absence of an output schema, the description is grossly incomplete. It does not explain what the update does, which fields are commonly updated, or how the inputs relate to the calendar entity. An agent cannot reasonably understand the tool's purpose or edge cases from this description alone; it is entirely inadequate for effective selection and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 42%, which is below the 50% threshold where the description must compensate. The description provides zero information about parameters, leaving the agent to rely on a schema that leaves many fields undocumented. With 52 parameters, including complex nested objects like recurring and lookBusyConfig, the lack of parameter guidance severely hampers correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('Calendar'), which distinguishes it from create or delete calendar operations. However, it is entirely generic—it does not indicate which of the 52 calendar attributes can be modified, leaving the agent to inspect the full schema to infer scope. It is not a tautology like 'Process', but it lacks the specificity seen in high-quality definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like calendars_create_calendar or calendars_update_calendar_resource. It does not state prerequisites, such as the need for an existing calendarId, nor does it mention any exclusions or sibling tools that might be more appropriate. The agent is left without direction on selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), destructiveHint=false, and idempotentHint=false, but the description adds no behavioral context. It does not state whether adding a contact to a workflow is reversible, whether it requires the workflow to be active, or what side effects might occur (e.g., triggering actions). Since the description carries little behavioral weight and annotations already cover the basic safety profile, it fails to add helpful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is appropriately brief, but it omits critical information. It front-loads the core action but sacrifices clarity and guidance. The structure is efficient but under-specified, earning a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description is inadequate. It does not mention any prerequisites (e.g., contact must exist, workflow must be active), expected outcomes, or potential errors. The openWorldHint annotation suggests side effects, but without elaboration the agent cannot anticipate consequences. Missing behavioral and usage detail makes this incomplete for safe and effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover contactId and workflowId with simple one-line descriptions, but eventStartTime has no description and is not explained in the tool description. The description does not clarify the format or semantics of eventStartTime, nor does it elaborate on the meaning of the IDs. With schema coverage at 67% and no compensating detail in the description, the agent has limited guidance on constructing valid calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add Contact to Workflow' states the verb and resource clearly, and the name itself conveys the action. However, it is nearly identical to the tool name and does not distinguish it from sibling tools like 'contacts_add_contact_to_campaign' or clarify what adding to a workflow entails (e.g., adding to a specific workflow stage). It is not a tautology in the strict sense, but it adds little beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention conditions such as 'use this to enroll a contact in a workflow' or contrast it with adding to a campaign or removing from a workflow. No exclusions or prerequisites are provided, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate those. However, the description adds no behavioral context beyond a bare verb: it doesn't mention what the response looks like, whether results are paginated, or what constitutes a 'task'. It neither contradicts nor meaningfully elaborates on the annotations, so it provides minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but this is under-specification rather than effective conciseness. It lacks any additional context that would help an agent understand the tool's behavior or scope. Every word is earned, but there are almost no words to earn.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description should clarify what 'all Tasks' means—whether it includes completed tasks, the expected return structure, and how it differs from related tools like contacts_get_task or contacts_get_all_notes. The description provides almost no context, leaving an agent with insufficient information to select and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the contactId parameter is documented in the schema. The description doesn't add any semantic detail about the parameter (e.g., required format, what the ID must reference). With high schema coverage, the baseline is 3, and the description adds nothing extra, so the score remains at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('all Tasks'), but it is overly generic. It doesn't specify that tasks are for a specific contact (implied by the contactId parameter and the tool name), and it fails to distinguish from sibling tools like contacts_get_task or contacts_get_all_notes. It's not a tautology, but it lacks the specific scope that would help an agent understand exactly what it retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are siblings like contacts_get_task, contacts_get_all_notes, and contacts_update_task that might be relevant, but no mention of selection criteria, prerequisites, or contexts where this tool is preferred. The agent is left without guidance on routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no extra behavioral context, such as return format or error conditions. It simply restates the action without value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively terse at just 'Get Note', which is under-specification rather than effective conciseness. It lacks essential context and reads as a stub.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with two required parameters, the description should at least mention what the response contains or how the note is identified. It provides none of that, and since there is no output schema, the burden falls on the description, which fails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with brief descriptions for id and contactId. The tool description adds nothing about the parameters, so it relies entirely on the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Note' conveys a verb and resource but is minimal. It doesn't specify the domain (contacts) or that it retrieves a single note, leaving the agent to infer from the tool name and the contactId parameter. It is distinguishable from contacts_get_all_notes by the singular 'Note', but the description alone is vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like contacts_get_all_notes or contacts_get_task. The description provides no context, so an agent cannot determine the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation), destructiveHint=false (not destructive), and idempotentHint=true. The description 'Update Note' adds no additional behavioral context such as side effects, required permissions, or response details. It neither contradicts annotations nor enriches them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), which is good for length, but it is under-specified. It does not provide enough context, so the conciseness detracts from usefulness. It is not wordy, but it does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description is completely inadequate. It does not explain what the note is, which fields can be updated, or what the return value looks like. An agent cannot confidently call this tool without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29% (only id and contactId have descriptions). The description does not clarify any of the other five parameters (body, color, title, pinned, userId). It adds zero value beyond the schema, which itself is incomplete. The agent is left guessing what fields are updatable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Note' clearly names the action (update) and resource (note), so an agent knows it modifies a note. However, it does not differentiate from sibling tools like contacts_create_note or contacts_delete_note, though the verb and resource are specific enough to avoid ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus any alternative. It does not mention prerequisites, conditions, or when a create/get/delete note would be more appropriate. No context is provided.
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?
The description does not disclose any behavioral traits beyond what the annotations already provide. Annotations indicate readOnlyHint=false and openWorldHint=true, implying side effects, but the description adds no context about the creation process, consequences, or side effects. Since it adds nothing beyond the verb 'Create', it fails to enrich the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, but it is under-specified for a tool with 19 parameters. While it wastes no words, it is not appropriately sized; it provides minimal value and could benefit from additional context without becoming verbose. The brevity here is not a virtue but a deficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (19 parameters, no output schema, and no behavioral annotations beyond basic flags), the description is severely incomplete. It does not explain what the agent is, what the parameters represent, or what the expected outcome is. The agent would need to rely entirely on the schema, potentially leading to misconfiguration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% parameter description coverage, so the baseline is 3. The description does not add any additional meaning to the parameters; it simply says 'Create an Agent' without explaining relationships, required vs optional, or any interpretative guidance. The schema already documents every parameter, so the description adds no value beyond what is structural.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('an Agent'), clearly indicating the tool's purpose. However, it does not distinguish from other agent-creation tools such as voice_ai_create_agent or agent_studio_create_agent, as the description is generic and lacks the 'conversation_ai' context that the tool name implies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, exclusions, or related tools, leaving the agent to infer from the name alone. The description is a single imperative with no supporting information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds no behavioral context beyond these. It does not mention that creation implies non-idempotency, potential side effects (e.g., generating invoice numbers, sending emails), prerequisites like business details or payment methods, or what happens on success. With no extra explanation, the description fails to inform the agent of any important behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two words, which is efficient, but it lacks any structure or front-loading of important information. It essentially restates the tool name without providing additional insight. While conciseness is good, it is under-specified rather than appropriately concise for a 23-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (23 parameters, 9 required, nested objects), the description is severely inadequate. It does not explain the purpose beyond creation, required fields, expected outcomes, or any caveats. The annotations and schema provide some structure, but the description fails to tie them together or provide any operational context. For a create operation this complex, the description is critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so most parameters already have descriptions in the input schema. The tool description itself adds no additional parameter semantics, but since the schema does the heavy lifting, a baseline of 3 is appropriate. The description does not clarify relationships or usage of complex nested objects beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Create Invoice'. It matches the tool name 'invoices_create_invoice' and is not a tautology, but it is minimal and does not differentiate from sibling tools like 'invoices_create_invoice_from_estimate' or 'invoices_create_invoice_template'. The purpose is understandable but lacks any distinguishing context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many invoice-related siblings (e.g., invoicing from estimate, creating templates, scheduling). The description gives no context about the appropriate use case, alternatives, or exclusions. This is a significant gap given the large sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only, not idempotent, and not destructive, but the description adds no behavioral context beyond the basic action of 'sending'. It doesn't clarify side effects (e.g., whether notifications are triggered, whether the invoice status changes, or the relevance of the action parameter). With only minimal annotation coverage, the description should carry more explanatory weight and fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—just two words—which violates the principle of appropriate sizing. It's under-specified, not efficiently concise. There is no structural benefit because it omits essential context that could help the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 8 parameters, including nested objects (autoPayment, sentFrom) and enums (action). The description provides no information about required fields, how to choose the action, or what the auto-payment configuration is. Without any hint of dependencies or special cases, an agent cannot reliably invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, which is relatively high, so the schema already documents most parameter meanings. The description itself provides no parameter-level guidance, but since the baseline is 3 for high coverage, it earns that baseline without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Send invoice'), so the primary purpose is understandable. However, it does not distinguish this from sibling tools like invoices_send_estimate or invoices_create_invoice, nor does it hint at the multiple sending methods (email, SMS, etc.) that the schema allows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, no context about prerequisites, and no exclusions. It is purely a two-word statement with zero situational information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a write operation (readOnlyHint false), not idempotent, not destructive, and open-world. The description adds no additional behavioral context such as side effects, permissions, or response format. It doesn't contradict annotations, but it provides zero extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no waste, front-loaded with the verb. It is appropriately sized for a one-parameter tool, though it's minimal enough that it could be mistaken for a heading rather than a helpful explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks any explanation of what 'last visited at' means or why an agent would call this tool. No output schema exists, and the description provides no context about the operation's purpose or effects. An agent has no information about the significance of this update or its place in the invoice workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the only parameter, estimateId, with 100% coverage. The description adds no additional meaning about the parameter, so the baseline of 3 applies; there is no extra info to boost the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update estimate last visited at' states a clear verb and resource, but it essentially paraphrases the tool name and adds no specifics. It does not differentiate from siblings like 'invoices_update_invoice_last_visited_at' beyond the word 'estimate' vs 'invoice', and provides no nuance about what updating 'last visited at' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, no prerequisites, no context on workflow. The description only states the action without any indication of suitable scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal and does not disclose side effects, permanence, or reversibility. Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds no context about what actually happens to files or folders, nor about permissions or idempotency. There is no contradiction, but the burden of behavioral disclosure falls almost entirely on schema, which is vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, consisting of only a noun-phrase. While it is concise, it is under-specified and lacks any actionable structure. It does not front-load critical information because there is almost no information at all.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk delete/trash operation, the description is grossly incomplete. It does not explain the difference between 'deleted' and 'trashed' statuses, the required format of filesToBeDeleted, potential consequences, or whether the operation is reversible. With no output schema and only vague parameter descriptions, an agent cannot confidently invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema itself. The description adds no parameter-specific context, but since the schema already explains each field, a baseline of 3 is appropriate. It does not compensate for any ambiguity in the schema, such as the structure of filesToBeDeleted objects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action (Bulk Delete/Trash) and target (Files or Folders). It is specific enough to convey the operation, though it does not differentiate from related media tools like medias_delete_media_content or medias_bulk_update_media_objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any mention of prerequisites or conditions. The description does not help an agent decide between this and other media-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive or idempotent. The description simply says 'Create', which is consistent but adds no additional behavioral context such as side effects, permissions required, or response behavior. More detail would be expected for a creation tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it is under-specified and does not provide enough information to be genuinely helpful. It is not concise in the sense of conveying essential details efficiently; it is simply too short.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested parameters, required fields, and no output schema, the description does not explain what happens after creation, how to verify success, or any specific constraints. The schema covers parameter format, but the description lacks context about the broader behavior and expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all parameters (100% coverage), including nested objects for live and test configs with required apiKey and publishableKey. The description adds no parameter-specific information, but since the schema covers everything, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Create new provider config') and a resource, but it is vague about what specifically constitutes a 'provider config'. It does not distinguish itself from sibling tools like payments_create_integration_provider, which could be confused with this tool. It is not a tautology, but it lacks specifity to fully convey purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, scenarios, or exclusions. The description does not help an agent decide between this and similar payments configuration tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as pagination behavior, filtering details, or response format. It does not contradict annotations, so a 3 is appropriate given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is extremely brief. While conciseness is generally positive, this level of under-specification means the description fails to convey any meaningful content. It is not a model of efficiency but rather a lack of specification, aligning with a 2 rather than a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the rich schema and annotations, the description is too thin to be considered complete. It does not explain what subscriptions are, how the list is paginated, what filters are available, or what the response includes (no output schema is present). For a tool with 13 optional parameters, this is inadequate contextual guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 13 parameters having descriptive text. The description 'List Subscriptions' adds no information about parameters, but the baseline of 3 is correct when the schema handles the documentation. No extra meaning is provided beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Subscriptions' is a tautology of the tool name payments_list_subscriptions, offering no additional specificity about the domain (payments) or the type of subscriptions. It does not distinguish from sibling tools like payments_list_orders or payments_list_transactions, and there is no mention of filtering capabilities or scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus similar listing tools such as payments_get_subscription_by_id or payments_list_transactions. The description gives no context about intended use cases, prerequisites, or exclusions, leaving the agent to infer usage from the schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. However, the description adds no behavioral detail beyond that—no mention of pagination, default limits, filtering behavior, or the nature of the returned data. Given the rich annotations, the bar is lower, but the description still contributes nothing beyond the name itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse—just three words. While it is front-loaded and free of fluff, it is under-specified rather than concise. It provides only the barest clause and forces the agent to rely entirely on the schema for any operational detail, which is not enough for a tool with 11 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters, no output schema, and multiple filtering options, the description is far too sparse. It omits any explanation of what a product review result looks like, how pagination works, which filters are most useful, or any edge cases. The annotations cover safety but not operational context, leaving the agent without sufficient information to correctly compose a request without inspecting the schema in depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 11 parameters with descriptions (100% coverage), so the schema carries the full semantic weight. The description offers no additional parameter context, but the baseline of 3 applies because the schema already documents each parameter thoroughly, including enums and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Fetch') and resource ('Product Reviews'), making its primary function unambiguous. It does not explicitly differentiate itself from sibling tools like 'products_get_reviews_count' or 'products_bulk_update_product_review', but the name and wording sufficiently convey that it retrieves review records rather than counts or modifies them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus related alternatives (e.g., getting a review count, updating or deleting reviews). The description provides no context about scenarios that favor this tool, no exclusions, and no mention of prerequisites or filters that might condition its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond the annotations. With readOnlyHint=false and destructiveHint=false, the agent knows this is a mutating action, but the description doesn't explain side effects, required permissions, or what 'attach' entails operationally. It merely restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single phrase with no fluff. However, it under-specifies: it omits usage context and parameter semantics, making it more under-specified than appropriately concise. A balanced description would add a few clarifying sentences without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no output schema, and minimal annotations, the description is severely incomplete. It doesn't explain the purpose beyond the verb, doesn't clarify required vs. optional parameters, and doesn't mention any integration steps (e.g., OAuth). An agent cannot correctly infer how to invoke this tool with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only accountId, companyId, and locationId have descriptions). The tool description provides no parameter explanations, leaving the 6 undocumented parameters (name, type, avatar, originId, username, verified) completely unexplained. The description does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Attach') and resource ('Tiktok profile'), which clearly distinguishes it from other attach tools in the sibling list (e.g., attach_facebook_page_group). However, it does not specify what the profile is attached to or any broader context, so it misses full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternative social media attach tools. It does not mention prerequisites, such as having completed TikTok OAuth, or conditions that would favor this tool over siblings like social_media_posting_attach_twitter_profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no extra behavioral context—no mention of return format, side effects, or dependencies. It does not contradict annotations, but it fails to contribute beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but under-specified. It lacks structure and front-loads no useful information. This is not conciseness that earns its place; it is insufficient to guide an agent effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is incomplete. It does not explain what constitutes a 'post', what information is returned, or how the ID and locationId parameters relate. Essential context for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with 'Post Id' and 'Location Id Defaults to GHL_LOCATION_ID when omitted' provided in the schema. The description itself does not elaborate on parameter semantics, but per the rule, a high-coverage schema sets a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get post' states a clear verb and resource, indicating the tool retrieves a post. However, it does not specify that it retrieves a single post by ID, nor does it distinguish from sibling tools like social_media_posting_get_posts (plural). It provides minimal context, though it is not a pure tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as get_posts, create_post, or edit_post. The description does not mention any prerequisites, exclusions, or scenarios that would favor this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, providing basic safety profile. The description adds no additional behavioral context such as side effects, required permissions, or data scope. It merely repeats the action without elaborating on what gets updated or how.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that essentially restates the tool name. While concise, it fails to add any informative content, making it wasteful rather than helpful. It is under-specified, not efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the tool has 5 parameters including a nested countries array. The description provides no context on what fields are updatable, how to structure the countries array, or when to use this operation. It is insufficient for an agent to call correctly without relying solely on the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters in the schema have descriptions (100% coverage), so the schema carries the burden of parameter explanation. The description provides no parameter-specific guidance, but per the rule, with high schema coverage a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Shipping Zone' states a clear verb and resource, but it adds nothing beyond what the tool name already conveys. It does not specify what aspects of the shipping zone can be updated (e.g., name, countries, rates) and does not differentiate it from sibling tools like store_create_shipping_zone or store_delete_shipping_zone beyond the verb itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus creating, deleting, or listing shipping zones, nor any mention of prerequisites or context. The agent is left to infer usage from the name alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint), but the description adds no behavioral context beyond the bare action. It does not disclose pagination behavior, filtering options, or other runtime aspects that would help the agent anticipate results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Search Users'), which is technically concise but under-specified. It does not front-load any useful context or nuance that would help the agent understand the tool's behavior or intended use, falling below the threshold of appropriate conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 11 parameters and no output schema, the description provides no overview of how the search works, what filters are available, or what the result set looks like. The schema documents individual parameters but not the overall purpose, leaving a significant gap for the agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 91%, so most parameters are documented in the schema itself. The description adds no additional meaning to the parameters; it simply repeats 'Search Users'. Given the high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('Search Users') but is vague and does not differentiate from sibling tools like users_filter_users_by_email or users_get_user. It lacks specificity about what kind of search (e.g., general, full-text) or how it differs from more targeted user lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as users_filter_users_by_email or users_get_user. The description gives no context for when to choose this over a more specific lookup, leaving the agent to infer usage from the schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (a write operation) and destructiveHint=false (not destructive). The description confirms the action but adds no new behavioral detail beyond what the annotations already convey. It doesn't disclose any side effects, auth requirements, or rate limits. Since the annotations already signal mutation, the description adds minimal value here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but extremely under-specified for a tool with 11 parameters and nested objects. It does front-load the main action but fails to provide any supporting structure or context. This is under-specification rather than effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (nested objects, 6 required fields) but the description offers no high-level context about how to use it, what the typical workflow is, or any constraints. The schema provides parameter details, but the overall context—such as the need for a Facebook page ID and integration setup—is entirely absent. The description is inadequate for an agent to confidently invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 11 parameters, so schema coverage is 100%. The description does not add any parameter-specific semantics beyond what the schema already documents. Given this high coverage, the baseline score of 3 applies—the description doesn't enhance or clarify parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create page lead form' with a specific verb and resource. However, it does not distinguish this from sibling tools like ad_manager_fb_create_conversation_form, which also creates a Facebook form type. Without additional context, an agent might confuse it with similar tools, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., having a Facebook page already integrated), and no mention of typical scenarios. The description simply states the action without any usage context, leaving the agent to infer everything from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so it is a non-destructive mutation, but the description adds no behavioral context beyond that. It does not explain side effects, like whether resuming an ad affects delivery immediately or if any permissions are required. The minimal annotation coverage leaves the description responsible for transparency, which it fails to provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two words and front-loaded, but it is under-specified rather than efficiently concise. It does convey the core action without fluff, earning a middle score, but the lack of structure (e.g., no sentence context) is not ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a mutation action, the description is severely incomplete. It does not mention what resuming an ad involves, what happens to the ad's status, or how the operation is confirmed. An agent would have no idea about expected outcomes or prerequisites, making this inadequate for a 2-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 50% coverage with only locationId having a description. The description 'Resume ad' adds nothing about adId or locationId. Given low schema coverage, the description should compensate but does not, leaving adId without any semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Resume ad' clearly states a verb (resume) and a resource (ad), which is unambiguous about the action. However, it does not differentiate from sibling tools like ad_manager_fb_resume_adset or ad_manager_fb_resume_campaign, relying on the tool name for that distinction. That meets the 'clear but no sibling differentiation' level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not specify that the ad must be in a paused state, nor does it mention any prerequisites or context. The description provides no usage direction at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), not idempotent, and non-destructive. The description adds no additional behavioral context, such as whether existing relations are overwritten, any side effects, or required permissions. It merely restates the action without enriching the agent's understanding of consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence, but it sacrifices clarity for brevity. It lacks essential details about the tool's purpose and usage, making it under-specified rather than efficiently concise. The structure is fine, but the content is insufficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and a domain that involves associations between records, this description is inadequate. It does not explain what a relation represents, how the parameters interrelate, or why a user would use this over other association tools. The schema helps but is not a substitute for a fuller description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema provides clear explanations for each parameter, including examples for firstRecordId and secondRecordId. The description itself adds no parameter-specific meaning beyond what the schema already offers, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Relation for you associated entities' states a specific verb (create) and resource (relation), but it's ambiguous what a 'relation' is in this context. It doesn't clearly distinguish from sibling 'associations_create_association', which likely creates an association definition. The description is not a tautology but lacks specificity about the entity types involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as needing an existing association or which record types are valid. The description gives no context about when this tool is appropriate, leaving the agent to infer from the parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate the tool is not read-only (readOnlyHint=false), not idempotent (idempotentHint=false), and not destructive (destructiveHint=false). The description adds no behavioral context beyond what the annotations already convey. It does not describe side effects, permissions, rate limits, or what happens to the contact or campaign after the add operation. With annotations carrying the safety profile, the description still provides no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, which is concise. However, it is so minimal that it borders on under-specification rather than efficient communication. It lacks any detail that would justify its brevity; the content is merely a paraphrase of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three parameters, one being a nested request body) and lack of output schema, the description is incomplete. It does not explain what a successful response looks like, potential error conditions, or any required preconditions (e.g., contact and campaign must exist). An agent would have to rely solely on the schema and general knowledge, which is insufficient for a mutation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter having a basic description (contactId: 'Contact Id', campaignId: 'Campaigns Id', body: 'Request body as defined by the HighLevel API.'). The tool description adds no further meaning to these parameters, so it does not enhance the schema's explanation. Baseline 3 is appropriate since the schema already documents them adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add Contact to Campaign' clearly states the verb and resource, but it is essentially a restatement of the tool name with no additional detail. It does not differentiate from sibling tools like 'contacts_add_contact_to_workflow' or 'contacts_add_tags', so it lacks the specificity needed for an agent to choose this over alternatives without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or conditions under which this tool should be preferred. The openWorldHint and other annotations give minimal context but the description offers nothing to help an agent decide when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so it is a write operation, but the description adds no behavioral detail beyond that. There is no mention of side effects (e.g., whether it creates a new message record, requires an existing conversation, or affects conversation state). The bur den falls entirely on the description, which is insufficient for a write operation with this complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and wastes no words, but it is under-specified for a tool with 17 parameters and nested objects. It is concise but not informative; the structure does not front-load key constraints or usage context. Adequacy is borderline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 params, nested objects, no output schema, no behavioral notes), the description is far too sparse. It fails to explain the purpose of an inbound message in the system, the required conditions (e.g., existing conversation), or how the payload should be composed. The agent must rely entirely on the schema, which is inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 17 parameters have descriptions. The tool description adds no extra meaning about parameters (e.g., how the 'type' field interacts with other fields or which combinations are typical). Baseline of 3 is appropriate because the schema carries the load, but the description offers no additional insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Add') and resource ('an inbound message'), which distinguishes it from the outbound sibling tool. However, it is terse and does not clarify what constitutes an inbound message (e.g., SMS, email, call) or that it operates on an existing conversation. The name reinforces the intent, but the description adds little beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that it should be used to log incoming messages into an existing conversation, nor does it reference sibling tools like conversations_send_a_new_message or conversations_add_an_outbound_message. The agent must infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true, but the description adds no behavioral context beyond the word 'Delete'. It does not disclose irreversible consequences, whether the folder is deleted from a specific location, or any permission requirements. The description fails to enrich the agent's understanding beyond what annotations supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded—a single, direct sentence. It is efficient and easy to parse, but it borders on under-specification. The brevity earns a high score for structure, though it sacrifices informational content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, an agent needs to know the effects (e.g., if deleting a folder also deletes its custom fields) and any requirements. The description lacks these details, leaving the operation underspecified. It is not adequate for safe invocation without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes locationId ('Location Id Defaults to GHL_LOCATION_ID when omitted') but id has no description. The tool description provides no clarification on what 'id' refers to (e.g., folder ID, location ID). With 50% schema coverage, the description does not compensate for the ambiguity of the required id parameter, leaving an agent uncertain about the exact value to pass.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action (Delete) and a specific resource (Custom Field Folder). It is unambiguous and matches the tool name well, though it does not explicitly differentiate from related delete tools like deleting a custom field. The verb-resource pairing is specific enough for an agent to understand the primary intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or context such as 'use this to remove a folder but not its fields'. The description offers no explicit or implicit direction for selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as return format, pagination behavior, or side effects. Since the annotations carry the core safety info, a neutral score of 3 is appropriate; it neither contradicts nor enriches the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with no filler. It is front-loaded and efficient. However, the extreme brevity borders on under-specification, which is penalized in other dimensions. For conciseness alone, it earns a 4, but it does not provide any structural elaboration that could aid comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and a large sibling set, the description is grossly incomplete. It does not mention what funnels are returned, how filtering works, what the response format is (no output schema), or any usage caveats. The description provides almost no context beyond the bare action, making it inadequate for correct invocation without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only locationId has a description). The description does not compensate for the missing parameter explanations—it says nothing about name, type, limit, offset, category, or parentId. With low schema coverage, the description should provide context for these parameters, but it remains silent. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Fetch List of Funnels'. It is clear that the tool retrieves a list of funnels. However, it does not differentiate from sibling tools like 'funnels_get_pages_by_funnel_id' or 'funnels_fetch_redirects_list'. Since it lacks sibling differentiation, it does not achieve a 5 but is clearly more than a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any filtering scenarios, required context, or how it differs from other funnel-related tools. With many sibling tools, the lack of usage direction leaves the agent without selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false, so the description adds little beyond the word 'Manage'. It does not disclose side effects, such as whether changing autoPayment.enable toggles payment processing, or if there are any irreversible changes. The description carries minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) and front-loaded with the action. However, it is grammatically flawed ('an schedule' instead of 'a schedule') and lacks specificity. While there is no filler, the brevity comes at the cost of clarity, making it under-specified rather than effectively concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested autoPayment object, multiple required parameters like scheduleId and id, no output schema), the description is inadequate. It does not mention required inputs or the expected outcome (e.g., returns the updated schedule). It fails to explain what 'manage' entails, leaving an agent without enough context to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, meaning most parameters have at least a short description (e.g., scheduleId as 'Schedule Id', autoPayment as 'auto-payment configuration'). The description adds no additional semantic meaning beyond the schema. It does not explain the role of autoPayment.enable or the meaning of nested fields like paymentMethodId, so it remains at the baseline for partially covered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Manage Auto payment for an schedule invoice', which indicates the tool deals with auto-payment on an invoice schedule. However, the verb 'Manage' is vague and doesn't specify the exact operations (enable, disable, update payment method). It doesn't explicitly distinguish itself from sibling tools like invoices_update_invoice_schedule, though its focus on auto-payment is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternative invoice-related tools. No mention of conditions, exclusions, or comparison to siblings such as invoices_update_and_schedule_invoice_schedule or invoices_schedule_invoice_schedule. The description leaves the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is mutable (readOnlyHint=false) and not idempotent, but the description adds no detail about what 'cancel' entails—whether it irreversibly removes the schedule, pauses it, or has other side effects. With annotations present, the description should clarify the exact behavior but does not, so it falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which is concise but lacks any structural elements like prerequisites or warnings. It is a single sentence that does not prioritize key information (e.g., that scheduleId is required). It is not verbose, but it is under-specified for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and three parameters, the description should explain expected outcomes or clarify the cancellation semantics. It does not mention return values, whether cancellation is reversible, or how the altId/altType defaults affect behavior. The description is insufficient for an agent to fully understand the tool's effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, including scheduleId, altId, and altType. The description adds no extra meaning about how these parameters are used or why scheduleId is required, but given full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Cancel an scheduled invoice' states a verb and object, but the object is ambiguous: it says 'scheduled invoice' while the tool name refers to 'invoice schedule'. This could mean canceling a recurring schedule vs. a specific scheduled invoice, and it does not differentiate from the sibling 'invoices_delete_invoice_schedule'. The purpose is recognizable but not precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives like delete_invoice_schedule or update_invoice_schedule. There is no mention of context, prerequisites, or distinctions between similar operations, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover readOnly/idempotent/destructive hints, so safety is disclosed. However, the description adds no behavior beyond 'List', failing to mention return format, pagination semantics, or any side effects. It doesn't leverage the annotation coverage to add 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse (two words), which is concise, but it lacks structure and fails to front-load critical context. It's under-specified rather than efficiently structured, so a middle score is warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters and no output schema, the agent needs contextual information about what the tool returns and how parameters interrelate (e.g., startAt/endAt, status, search). The description provides none of this, making it inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all parameters. The description adds no parameter-level meaning; baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List templates' names a verb and a resource but is vague – it doesn't specify which templates (invoice templates) or the context from the tool name. It is not a tautology but lacks clarity on scope and sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like invoices_list_estimate_templates or invoices_list_invoices. No mention of filters, pagination, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no behavioral context beyond the obvious mutation, such as what gets overwritten, authentication needs, or side effects. It neither contradicts nor enriches the annotation-provided safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is extremely concise and front-loaded with the action. However, for a tool with 25 parameters and nested objects, it is under-specified—conciseness here crosses into incompleteness, so a 3 reflects the balance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (25 parameters, many optional nested objects, no output schema), the description is grossly insufficient. It fails to mention any conditional requirements, special formats, or operational context. The schema covers param definitions, but the description offers no overview, examples, or clarifications that an agent would need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (84%), so the schema itself documents most parameters. The description adds no parameter-level meaning, but with such high coverage, a baseline of 3 is appropriate. The description does not compensate for the 16% of undocumented parameters, but that is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-resource pair ('Update invoice') but provides no additional scope or differentiation from sibling invoice tools (e.g., invoices_update_invoice_template). It is not a tautology, but it adds nothing beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or context such as 'use this to modify an existing invoice's fields'. The description is entirely silent on usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is well covered. However, the description adds no behavioral context beyond the annotations—it does not mention default behavior (which is in the schema) or any edge cases. Since the description doesn't add value over annotations, it scores low on this dimension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—only three words—which is efficient but under-informative. It is not poorly structured, but it borders on being too terse. A single sentence explaining the purpose and possibly the return type would be more helpful without adding much length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and only one optional parameter, the description still fails to convey what the response will contain (e.g., a list of timezone IDs, names, offsets) or any limitations. While annotations cover safety, the description leaves critical details about the return value implicit, making it incomplete for an agent to fully anticipate the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter 'locationId' with a description including its default behavior ('Defaults to GHL_LOCATION_ID when omitted'), so schema coverage is 100%. The description itself adds no parameter information. According to the rubric, with high schema coverage, a baseline of 3 is appropriate because the description doesn't need to repeat schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch Timezones' is a terse restatement of the tool name and provides only a verb and resource without any scope or detail. It does not clarify whether this returns timezone identifiers, offsets, or something location-specific. There are no sibling timezone tools to distinguish from, so the lack of differentiation is less critical, but the purpose is still vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, no context about prerequisites, and no exclusions. Even for a simple read operation, some indication of typical use cases (e.g., 'to retrieve timezone settings for a location') would be helpful. The absence of any usage direction leaves the agent to infer entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond the verb 'update'. It doesn't disclose whether the operation is a partial or full replacement of the schema, what happens to existing fields, or any side effects. Since the description carries no additional behavioral insight beyond what the annotations already declare, it falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and free of fluff. However, it is under-specified and lacks any structural breakdown of the operation. While it doesn't waste words, it also doesn't provide enough substance to be considered well-structured. It's not a tautology, but it's on the border of being too terse for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 parameters and no output schema, this description is incomplete. It doesn't mention what the response will be, which fields are updatable, or any important preconditions (e.g., the key format, the need for a custom object prefix). The description gives only a one-liner and leaves the agent to infer most operational details from the schema and annotations. Given the complexity and the absence of an output schema, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with all five parameters documented (key, labels, locationId, description, searchableProperties). The description itself doesn't add any parameter-specific meaning, but the baseline is 3 given high schema coverage. It doesn't contradict or enhance the schema, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Update') and target ('Object Schema'), but the phrase 'By Key / Id' is misleading because the schema only includes a 'key' parameter, not an 'id'. It also doesn't explicitly say 'custom object' (only in the tool name), and doesn't distinguish from the sibling 'objects_update_object_record' which updates a record, not a schema. It's clear enough that it updates a schema, but the ambiguity around the identifier and the lack of explicit resource specificity prevent a higher score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It doesn't mention that it's for modifying an existing custom object schema (as opposed to creating or getting one), nor does it exclude scenarios. The description provides no context about prerequisites or when this tool is the right choice among the many object-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive operation. The description simply states 'Create', which aligns with annotations but adds no additional behavioral context such as uniqueness constraints, authentication requirements, or potential side effects. The description adds minimal 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase—'Create White-label Integration Provider'—which is terse but not structured or elaborative. It lacks a complete sentence and offers no hierarchy of information, making it less helpful than a well-organized description that front-loads key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, 5 required, and no output schema, the description is critically incomplete. It does not mention the return value, any constraints like uniqueName format, or the purpose of white-labeling. An agent would struggle to understand what 'white-label' implies without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with detailed descriptions for all seven parameters, so the baseline is 3. The description itself adds no parameter information, but the schema already carries the full burden, so no deduction is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'White-label Integration Provider', making the primary action unambiguous. However, it does not distinguish this tool from similar siblings like payments_create_integration, relying on the 'White-label' qualifier for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about the intended use case. An agent receiving only this description would have no idea when to prefer it over other integration-provider creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, establishing that this is a safe, non-destructive update. The description adds no behavioral context beyond the word 'Update' — it does not explain consequences, required permissions, or any side effects. It neither contradicts nor enriches the annotation profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise — one short sentence. While it is not verbose, it is too underspecified to be considered well-structured. It lacks any substance that would earn its place beyond repeating the tool name, so it falls below a strong conciseness score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 9 parameters and no output schema, the description is severely incomplete. It does not explain what a successful update entails, the meaning of required fields like 'status', or expected outcome. The agent is left to infer from the schema alone, which is insufficient for a non-trivial operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 9 parameters, so the baseline is 3. The description itself contributes no parameter-level meaning; it repeats the action but does not clarify which parameters are essential or how they relate to the update operation. All semantic load falls on the schema, which is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('Product Reviews'), which identifies the action and subject. However, it is essentially identical to the tool name and provides no detail on what aspects of a review can be updated (e.g., rating, headline, reply), making it too generic to distinguish from related tools like products_bulk_update_product_review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention bulk updates, read-only review retrieval, or any conditions that would select this tool over siblings. The absence of any usage context leaves the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating operation (readOnlyHint false) and idempotent (idempotentHint true). The description adds nothing beyond the verb 'Update' about side effects, required permissions, or what happens to existing settings. Since annotations cover the basic safety profile, this earns a 2 – it's present but does not enrich the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short – three words – which is concise but under-informative. It doesn't front-load any key constraints or context. For a tool with 15 parameters, this level of brevity is not helpful; it's more terse than effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, 2 required, no output schema, and no explanation of conditional pricing or carrier rate distinctions), the description is grossly incomplete. It doesn't tell an agent what typical update scenarios look like or which parameters are commonly used together. The schema provides parameter semantics, but the description fails to synthesize them into actionable guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 15 parameters have descriptions. The tool description adds no additional meaning; it just names the operation. According to the guidelines, when coverage is high the baseline is 3, and the description doesn't compensate or add clarity beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Shipping Rate' states a clear verb and resource, so it's not a tautology. However, it provides no detail about what fields can be updated or scope, and it doesn't distinguish from sibling update tools like store_update_shipping_carrier or store_update_shipping_zone beyond the resource name. It's minimally acceptable but lacks the specificity that would help an agent separate it from similarly-named tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives. It doesn't mention that it requires an existing shipping rate ID, or that creation should use store_create_shipping_rate. An agent has to infer from the schema that shippingRateId and shippingZoneId are required, but the description itself offers no context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description 'Upsert adset' adds no additional behavioral context—it does not explain what happens to existing adsets when an ID is provided, whether a new one is created when omitted, or any side effects like overwriting. With annotations present, the description still fails to add meaningful behavioral details, so I give a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, containing only 'Upsert adset'. While it has no fluff, it is essentially a restatement of the tool name and provides no informative content. This mirrors the 'process' example, which was deemed under-specified rather than concise. The lack of any elaboration makes it more of a placeholder than a meaningful description, so I rate it a 2.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool is complex with 13 parameters, nested objects, no output schema, and a required campaignId. The description 'Upsert adset' is severely inadequate—it does not explain the upsert behavior, dependencies, return values, or any operational context. The agent must rely entirely on the schema and annotations, which do not convey the overall purpose or workflow. For such complexity, this description is grossly incomplete, earning a 1.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all 13 parameters, including nested objects like audience and budget. The description 'Upsert adset' adds no additional semantic meaning beyond the operation itself; it does not explain parameter relationships or provide usage context. With high schema coverage, the baseline is 3, and the description does not elevate it, so I keep a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert adset' clearly states a specific verb (upsert) and resource (adset), indicating create-or-update on an ad set. It is not a tautology and distinguishes from siblings like upsert_campaign or upsert_ad because it names 'adset'. However, it lacks any detail about what an adset is or why it's used, but the name and schema cover that. A 4 is appropriate for a clear but minimal statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., an active Facebook integration, existing campaign), nor does it explain scenarios where this tool is preferable over upsert_campaign or pause_adset. Without any context, an agent cannot determine when to invoke it. This is a clear gap, warranting a 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds no additional behavioral context such as what the response contains, whether it requires authentication, or any side effects. It is neutral and relies entirely on 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant wording. It is front-loaded with the action and resource. However, it is extremely brief and could include a bit more detail without becoming verbose, so it earns a 4 rather than 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what the agent can expect in the response (e.g., campaign structure fields). It does not mention return format, prerequisites like an existing Google Ads integration, or any limitations. The description is too thin to fully prepare an agent for a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for both parameters. 'adId' is described as 'Ad identifier' and 'locationId' includes a default note. The description itself adds no extra meaning beyond what the schema already specifies, 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.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Google campaign by ID' clearly indicates it fetches a campaign by its identifier, and it is not a tautology. However, it does not differentiate this tool from siblings like ad_manager_google_get_conversion_by_id or ad_manager_google_get_audience_by_id beyond the resource name, which is already in the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites such as an existing Google Ads integration, nor exclusions for when to use other tools like ad_manager_google_get_campaign_reporting. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the name—it doesn't explain whether authentication is required, what the response contains, or any side effects (which are none). With annotations present, the bar is lowered, but the description still fails to add any useful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (four words), which is not verbose, but it is under-specified. It is front-loaded but provides minimal information. While it doesn't waste words, it could benefit from a brief mention of what the user represents or what callers can do with the result, so it earns a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a read-only tool with no output schema and no required parameters, so the description should explain what the returned 'current user' actually is (e.g., profile information, credentials). Without that, an agent can't predict the output or use it correctly. The description is too sparse to be complete for a tool that returns data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for locationId is complete ('Location identifier Defaults to GHL_LOCATION_ID when omitted.'), and schema coverage is 100%, so the baseline is 3. The tool description itself adds no additional parameter semantics, but since the schema already documents the only parameter, no extra credit is earned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('current Google user'), which distinguishes it from sibling tools like ad_manager_fb_get_current_user and ad_manager_li_get_current_user by platform. However, it doesn't clarify what 'current' means (e.g., authenticated user) or what specific data is returned, so it stops short of full clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that this is the Google variant of current-user retrieval, nor does it address prerequisites like OAuth or the meaning of the locationId parameter. An agent has to infer usage from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, conveying that this is a safe, read-only operation. The description adds no additional behavioral context such as return format, authentication needs, or potential variability (openWorldHint). Thus, it provides no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence with no redundancy. It is front-loaded and efficient, though it could afford a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what the tool returns; it does not. It also fails to define 'integration' or any prerequisites. While the operation is simple, an agent needs at least a hint of the return payload to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the sole parameter locationId has a clear description including a default), so the baseline is 3. The tool description does not add any parameter-level semantics; it relies entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('Google integration'), but is vague about what an integration is or what it returns. It distinguishes from siblings by the 'Google' qualifier (e.g., ad_manager_fb_get_integration), but lacks specificity about the integration's nature or contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like ad_manager_fb_get_integration or ad_manager_li_get_integration. The description does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds no behavioral detail beyond the name, such as whether it creates or updates, required permissions, or effects on existing data. It does not contradict the annotations, but it also adds no value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but under-specified for a tool with five parameters including nested objects. It lacks necessary elaboration and structure, making it more under-specified than appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested dimensions, exclusion dimension, no output schema), the description is grossly inadequate. It does not explain the purpose of dimensions, the meaning of upsert, or expected behavior, leaving the agent with insufficient context to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema parameter descriptions are comprehensive (100% coverage), so the baseline is 3. The description contributes no additional parameter semantics; it does not clarify relationships between parameters or provide usage hints beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Upsert audience' clearly identifies the action (upsert) and the resource (audience), which distinguishes it from sibling get/delete tools. However, it lacks detail on what an audience is or how it differs from other upsert tools like upsert_segment, so it is not fully differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not explain upsert semantics (create-or-update), when to choose it over get/delete or other upsert tools, or any prerequisites. This leaves the agent without selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description adds no behavioral detail beyond the word 'upsert'. It does not disclose what happens to existing campaigns, whether settings are overwritten, or any permission requirements. The description adds no value over annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse ('Upsert Google campaign') and provides no additional instructive content. It essentially repeats the tool name and lacks any meaningful structure or value beyond the bare minimum.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 22 parameters, nested objects, and no output schema, the description fails to provide essential context about behavior, required fields, or how to use the tool correctly. An agent would be left entirely dependent on the schema, which is insufficient for such a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are documented in the schema. The description adds no additional meaning about parameters, but since the schema fully covers them, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the primary action (upsert) and the resource (Google campaign), which clearly identifies the tool's purpose. It also differentiates from sibling upsert tools for other platforms (fb, li) by specifying 'Google'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or conditions (e.g., when to create vs update, or when to choose Google over Facebook/LinkedIn). No contextual cues for appropriate usage are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows it's a non-idempotent mutation. The description adds nothing beyond the verb 'create' — no disclosure of side effects, required account context, or consequences. It does not contradict annotations, but fails to provide behavioral context beyond what the verb implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a two-word phrase that is extremely sparse. It lacks structure and does not front-load any important caveats or context. This is under-specification rather than useful conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 required parameters, nested objects (content, owner, creationLocale), and no output schema, a two-word description is entirely inadequate. The agent receives no explanation of what a lead form entails, how to structure the content, or what the expected outcome is. This is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — each of the 8 parameters has a description. The tool description adds no parameter-level meaning, so it relies entirely on schema. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Create lead form'. This distinguishes it from siblings like ad_manager_li_get_lead_forms (create vs get). However, it doesn't explicitly differentiate from other creation tools such as ad_manager_fb_create_page_lead_form, though the platform is implied by the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or when to prefer this over other lead form creation tools. The description is purely a verb+noun with no contextual instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description does not need to repeat those. However, it adds no additional behavioral context, such as whether the created brand board is immediately available, whether it requires specific permissions, or what the response shape is (especially since there is no output schema). The description is purely a single verb phrase with no disclosure beyond the annotation-provided flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, which is concise. However, it is under-specified—it lacks any elaboration that would earn its place beyond stating the obvious. It is not verbose, but it is so minimal that it feels more like a label than a helpful description. It is front-loaded with the core action, but the brevity limits its usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has nine parameters, no output schema, and no usage context, the description is far from complete. It does not explain what the caller should provide (beyond the schema), what the result is, or any dependencies like locationId or parentId. The schema covers parameter details, but the description leaves the agent without a sense of the overall workflow or expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all nine parameters are documented in the input schema with their own descriptions. The tool description itself mentions none of them, so it does not add meaning beyond what the schema provides. Per the rubric, with high coverage, a baseline of 3 is appropriate; the description neither helps nor hinders parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new brand board' clearly states the action (create) and the resource (brand board), which distinguishes it from sibling tools like delete, get, and update. It is a proper clause rather than a tautology, though it closely mirrors the tool name and title. It does not add any additional context about what a brand board is or what creation entails, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as updating or getting a brand board. It does not mention prerequisites, like the need for a locationId, nor any conditions that would make this tool the appropriate choice. An agent must infer entirely from the name that this is for creating new records, with no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds nothing beyond a bare action; it does not disclose pagination behavior, the meaning of 'availability schedule', or the fact that locationId defaults to GHL_LOCATION_ID (which is in the schema but not in the description). Since the annotations already cover the basic traits, the description's contribution is minimal and does not reveal any behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase with no fluff or redundant information. It is front-loaded with the action and resource. However, it is almost too terse to be useful; while concise, it sacrifices clarity. Still, there is no unnecessary wording, so it earns a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a tool with five parameters and a required userId. It does not clarify whether it returns all schedules or a single one, nor does it provide any context about the response or usage. With a required parameter and sibling tools that suggest a more granular lookup, the description leaves significant gaps for an agent deciding how and when to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters having clear descriptions in the input schema. The tool description adds no parameter-specific insight, but the baseline for high coverage is 3. The description does not explain how parameters like userId or calendarId affect results, but the schema does, so the description is not required to repeat them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('List') and a resource ('user availability schedule'), but it is ambiguous whether it lists all schedules or a single schedule. The tool name says 'get_all_schedules' while the description uses the singular 'schedule', and it does not differentiate from sibling tools like calendars_get_schedule_by_id or calendars_get_calendars. This leaves the agent unclear about the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of when to choose this over calendars_get_schedule_by_id or calendars_get_calendars, nor any context about filtering by user or calendar. The description simply states the action without any conditional usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already indicate (readOnlyHint=false, destructiveHint=false, etc.). It does not explain whether the update is a full replacement or partial, what happens to unspecified fields, or any side effects. The annotations cover some safety aspects, but the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant phrasing. It is concise and front-loaded with the core action. However, it is also extremely brief, which limits its usefulness, but for conciseness alone it earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (one required) and no output schema, the description is minimally helpful. It does not explain what constitutes a 'schedule', what the rules field expects, whether the update is partial or full, or what the response contains. An agent would need to guess many details, making the definition incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have descriptions in the schema (coverage 100%), so the schema already explains each field. The tool description does not add any additional nuance, such as how 'rules' should be structured or how timezone interacts with schedule. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('user availability schedule'), indicating a write operation on a schedule. However, it does not specify which aspects are updated (e.g., name, rules, timezone) or provide any differentiation from sibling tools like calendars_create_schedule or calendars_get_schedule_by_id. It is more specific than a tautology but still vague about the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when to prefer this over other schedule-related tools, or any exclusions. An agent would have to infer usage from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not required to restate these. However, it adds no additional behavioral context such as what the search returns, pagination behavior, or any side effects. It neither contradicts annotations nor enriches them, falling short of the bar for adding value beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), which avoids verbosity, but is under-specified. It lacks a sentence even—just a phrase—and does not front-load any useful context. For a tool with three parameters and no output schema, this is not appropriately sized; it sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and three parameters, the description fails to convey essential context such as the return format (e.g., a list of agents), how the search matches (by name), or typical usage scenarios. It provides zero information about what happens when the tool is invoked, making it inadequate for an agent to understand the tool's behavior or anticipate results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (limit, query, startAfter) have thorough descriptions in the schema covering pagination (limit, startAfter) and search criteria (query must be lowercase). Since schema description coverage is 100%, the baseline is 3. The description 'Search Agents' provides no additional meaning about how parameters interact with the search, so it adds no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Agents' clearly states a verb (Search) and resource (Agents), making the primary purpose evident. However, it does not differentiate from sibling tools like conversation_ai_get_agent or conversation_ai_list_actions, nor does it specify the search field (agent name) which is only hinted at in the schema. It is clear but lacks specificity to distinguish it from similar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of when a search is appropriate over a direct get-by-id or list operation, no exclusions, and no reference to sibling tools. The description is too sparse to provide any usage context beyond the implied 'search' action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the basic safety profile. The description adds no additional behavioral context, such as side effects on related resources or error handling behavior. Since it adds nothing beyond the mutation implied by the name, it does not enhance transparency 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence: 'Update message status.' It is front-loaded and contains no filler. While it is very short, it is efficient and directly states the action without unnecessary words, so conciseness is high.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, including a nested object, and no output schema, the description lacks essential context. It doesn't explain what happens after the update, how statuses map to delivery outcomes, or what the response contains. The sparse description is insufficient to fully understand the tool's behavior for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, including enums for 'status' and explanations for 'error', 'recipients', and 'emailMessageId'. The description does not add any parameter-specific meaning; it relies entirely on the schema, which is adequate. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb 'Update' and resource 'message status', which identifies the core action. However, it doesn't specify what statuses are available, how the status is updated, or how it differs from sibling tools like 'conversations_update_conversation'. It's understandable but lacks differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no exclusions. The description simply states the action without any context about appropriate use cases or when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and idempotency profile. The description adds no additional behavioral context (e.g., pagination behavior, response format, or default scoping). It does not contradict the annotations, so a 3 is appropriate as the annotations carry most of the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three words), which is efficient but under-specified. It front-loads the purpose but omits any parameter or usage details. While every word earns a place, the lack of structural context (e.g., mentioning available filters) makes it less helpful than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters, no output schema, and a 9% schema description coverage, the description is grossly incomplete. It does not explain what the tool returns, how parameters affect results, default behaviors, or any necessary context for correct invocation. The tool is effectively opaque to an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9% (only locationId has a description), and the description mentions none of the parameters. The other 10 parameters (name, limit, offset, search, archived, originId, parentId, sortByDate, templatesOnly, builderVersion) have no semantic explanation in either the schema or the description. This is a critical gap for a tool with 11 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch email templates' clearly states the action (fetch) and the resource (email templates), and distinguishes from siblings like emails_create_template, emails_delete_template, and emails_update_template. It does not specify scope or filters, so it loses one point for not being more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like locations_get_all_or_email_sms_templates, which also fetches templates. No mention of prerequisites, scope (e.g., location-level), or when to prefer this over other fetch methods. The description is a bare statement with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context, such as the return format (a count) or potential edge cases (e.g., handling of missing funnels). It does not contradict annotations, but it contributes no additional value beyond what the annotations already guarantee.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it is under-specified. It does not front-load key information like the return type or scoping, and it reads as a minimal fragment rather than a structured explanation. It earns a middle score for its brevity but lacks substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters and no output schema, the description is insufficiently complete. It does not explain what the count includes (e.g., drafts vs. published pages), how it relates to the sibling pages-fetching tool, or any filtering or pagination. An agent cannot fully anticipate the tool's behavior or output from this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only locationId has a description). The tool description does not explain the meaning or usage of `name` or `funnelId`, nor does it reiterate the default for locationId. Given the low schema coverage, the description should compensate but fails to provide any parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch count of funnel pages' clearly states the action (fetch) and the resource (count of funnel pages). It is specific and distinct from the sibling tool `funnels_get_pages_by_funnel_id` which returns pages themselves, although it does not explicitly name the sibling. The purpose is unambiguous given the tool name and description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool over alternatives, nor does it mention any exclusions or prerequisites. An agent is left to infer the context from the sibling names alone, which is insufficient for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds nothing beyond that—no mention of pagination, default behavior (e.g., defaults to GHL_LOCATION_ID), or what the response contains. It does not contradict the annotations, but it also does not enrich 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase with zero wasted words. It is front-loaded with the primary action. However, it is so minimal that it approaches under-specification; conciseness is not the issue, but the lack of content is. Still, for pure conciseness, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has five parameters including pagination (limit/offset) and search, and no output schema exists, the description should mention important context such as default altId behavior, pagination semantics, or that it returns a list of templates. The description covers none of this, leaving agents without guidance on how to use the parameters effectively or what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (altId, limit, offset, search, altType) are already documented in the schema. The description adds no parameter-level detail, so it relies entirely on the schema. Baseline of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Estimate Templates' states a clear verb and resource, but it is essentially the tool name repeated. It does not differentiate this tool from siblings like invoices_list_estimates (which lists estimates, not templates) or invoices_list_invoice_templates (which lists invoice templates). The purpose is clear but lacks specific scope or distinguishing details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are many similar list tools (e.g., invoices_list_estimates, invoices_list_invoice_schedules), and no context is given about which one to choose. It does not mention any prerequisites, exclusions, or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete a knowledge base' is consistent but adds no behavioral context beyond what annotations provide. It does not mention irreversibility, impact on associated data, or any 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no fluff or redundancy. It is front-loaded and to the point. However, the extreme brevity means it omits crucial details, but conciseness itself is high.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive operation with a single parameter and no output schema, the description is incomplete. It lacks any explanation of the parameter, how to identify the knowledge base, or the consequences of deletion beyond what annotations imply. The agent has insufficient information to call this tool correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the knowledgeBaseId parameter, and the description provides no explanation of what this parameter represents, how to obtain it, or its format. The agent is left to infer that knowledgeBaseId identifies the knowledge base to delete, but no details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (a knowledge base). It is specific and unambiguous, and the name reinforces it. However, it does not differentiate from sibling tools like knowledge_base_delete, which could cause confusion about which delete operation to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, no prerequisites, and no conditions. The description is purely a statement of action with no context on how it fits into a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations explicitly declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, which already covers the destructive and idempotent nature. The description simply says 'Delete', which is consistent with the annotations and adds no additional behavioral context such as what gets destroyed, reversibility, or side effects. It neither contradicts nor enriches beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded with the core action, but it is borderline under-specified rather than genuinely concise in a helpful way. Still, it earns a 4 for being terse and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description provides insufficient context. It fails to distinguish this tool from the similar custom_fields_delete_custom_field, does not mention that it's scoped to locations, and offers no guidance on expected return values or consequences. While schema covers parameters and annotations cover danger, the description leaves an agent guessing about applicability and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both parameters (id and locationId) at 100% coverage. The description adds no further parameter semantics; the schema already documents that locationId defaults to GHL_LOCATION_ID when omitted. Since the schema does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action (Delete) and the resource (Custom Field), so it's a clear verb+resource combination. However, it does not differentiate this from the sibling custom_fields_delete_custom_field tool, which performs a very similar action. Without context, an agent cannot tell which delete tool is appropriate for a given scenario.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description only offers the imperative 'Delete Custom Field' with no mention of context, prerequisites, or exclusion conditions. An agent has no information about when this is the correct tool among the dozens of delete tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds no extra behavioral context (e.g., side effects, required permissions, or implications of status changes). It merely restates the action without enriching the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three words), which is efficient, but it lacks structure or front-loaded detail. While it avoids verbosity, it fails to convey any usage nuance, making it under-specified rather than elegantly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters including an enum and an optional field, the description is inadequate. It does not explain the effect of changing status, when 'lostReasonId' is required, or any business logic. With no output schema and limited annotation detail, an agent cannot fully understand the tool's behavior from this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention any parameters. The schema describes 'id' and 'lostReasonId' but the 'status' field lacks a description. With only 67% schema coverage, the description should compensate for the missing parameter semantics but does not, leaving the agent without clarity on status meaning or when to provide lostReasonId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Opportunity Status' provides a clear verb and resource, indicating the tool modifies the status field of an opportunity. It is specific enough to distinguish from generic update tools like 'opportunities_update_opportunity', though it doesn't explicitly name the status field or differentiate from other status-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus siblings such as 'opportunities_update_opportunity' or when not to use it. There are no prerequisites, context, or exclusions mentioned, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the tool is a write operation but not destructive. The description adds no behavioral context beyond the word 'Create', such as idempotency, side effects, or result handling. It doesn't contradict annotations but fails to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words) which is efficient in wording but severely under-specified for a tool with 18 parameters and nested objects. It lacks any structure or front-loaded key details. The conciseness is not a strength here because it omits essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (18 parameters, nested objects, no output schema), the description is grossly incomplete. It doesn't mention required fields, the effect of the tool, what constitutes a successful creation, or any constraints. An agent cannot correctly call this tool without relying entirely on the schema, and even then, behavioral expectations are unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 94% description coverage, so most parameters are already well documented. The description text adds nothing about parameters. Given the high coverage, a baseline score of 3 is appropriate; the description fails to add any extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Product' clearly identifies the verb (create) and resource (product), which is sufficient to distinguish from sibling tools like products_create_product_collection or products_create_price_for_product. However, it doesn't specify the product types or any distinguishing behavior beyond the generic name, so it's clear but not particularly detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, required parameters, or typical use cases. There is no mention of the required 'name' and 'productType' fields, or that locationId defaults to GHL_LOCATION_ID. An agent would have to infer usage solely from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which convey a safe, read-only operation. The description adds no behavioral context beyond that—no mention of return format, side effects, or typical use cases. With annotations present, the bar is lower, but the description still fails to provide any additional transparency, so it does not earn more than a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence and no fluff. It is front-loaded with the key verb and resource. While it is under-informative, it is not verbose or poorly structured, so it earns a strong score for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and the description does not explain what the response will look like or what the categories pertain to. It also fails to disambiguate from similar get-tool siblings. For a tool with only two parameters and minimal context, this is insufficient—an agent would lack understanding of expected return data or when this tool is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter descriptions: 'id' is Category Id and 'locationId' is Location Id Defaults to GHL_LOCATION_ID when omitted. The description itself adds no parameter information; it only restates the operation. Given high schema coverage, baseline is 3, and the description does nothing to raise it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('categories') with an identifier inference ('by id'), so it is not a tautology. However, it is ambiguous about what these categories represent and does not differentiate from sibling tools like social_media_posting_get_categories_location_id or social_media_posting_get_tags_by_ids. The specificity is minimal, making it clear only at a very basic level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention the locationId parameter's role or suggest when to use get_categories_location_id instead. The description implies usage only by stating its function, but lacks any contextual or comparative directions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds no further behavioral context, such as what the tool returns, whether it requires user interaction, or that it is a prerequisite for other operations. It does not contradict annotations, but provides no incremental transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no redundancy or filler. It is efficiently concise, though it may be too terse to convey sufficient detail. Structure is simple and front-loaded, so no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that starts an OAuth flow, the description lacks essential context: what the output is (e.g., a redirect URL), what parameters are needed for which scenarios, and what happens after calling it. Without an output schema, the agent has no idea what to expect. This is inadequate for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. However, the parameter descriptions ('Page', 'User Id', 'Reconnect') are generic and largely unhelpful. The tool description offers no additional clarification about what these parameters mean in the OAuth context. It neither improves nor contradicts the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Starts OAuth For Twitter Account' gives a clear verb and resource, but 'starts OAuth' is vague without explaining what initiating OAuth entails (e.g., returning a URL or beginning a token exchange). It does distinguish from siblings that mention other platforms, but not from other OAuth-start tools beyond the platform name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, prerequisites (e.g., needing an existing Twitter integration), or the expected next steps after calling it. The description simply states the action without context.
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?
The description adds no behavioral context beyond the verb 'Create'. Annotations already indicate it is a write operation (readOnlyHint: false) and not idempotent, but the description does not disclose any side effects, authentication needs, or rate limits. It simply restates the action, providing zero value beyond what is available from annotations and the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of only three words. While there is no wasted text, it also contains no front-loaded critical information or hints. It mirrors the tool name and title, making it redundant. True conciseness would complement the schema, but this is under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters and no output schema, the description should provide more context about the tool's behavior, return values, or why one would use it. It does not explain what happens upon creation, any constraints (e.g., callbackUrl must be public—though that is in schema), or how the tool integrates with other shipping tools. The description is incomplete for an agent to make an informed call without assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—all six parameters (name, altId, altType, services, callbackUrl, allowsMultipleServiceSelection) have descriptive comments. The description itself does not elaborate on any parameters, but the high coverage means the baseline is 3. The schema already documents required and optional fields, so no additional explanation is needed here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Shipping Carrier' clearly states a specific verb and resource. It distinguishes from sibling tools like 'store_create_shipping_rate' and 'store_create_shipping_zone' by naming 'Carrier' explicitly, leaving no ambiguity about the object being created. However, it lacks any additional qualifiers or context that would elevate it to a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or related tools such as 'store_update_shipping_carrier' or 'store_list_shipping_carriers'. The agent is left to infer the usage solely from the schema and name, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is not read-only, not idempotent, and not destructive, which covers basic safety. The description adds no behavioral traits beyond the verb 'Create', such as side effects, required existing entities, or response behavior. It doesn't contradict annotations but contributes little beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
At three words, it is extremely concise and front-loaded, but it may be under-specified for an operation with 14 parameters. It is not verbose or unstructured, but it also doesn't provide any context that would warrant a higher score for conciseness. The brevity is acceptable for a simple create, but lacks substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 14 parameters, 8 required, and no output schema, the description provides no overall context about shipping rate creation, such as the relationship between conditions, carrier rates, or typical use. The schema helps per-parameter, but the tool description leaves the agent without a high-level understanding of the operation's purpose and constraints. Incomplete for a complex creation endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 14 parameters are described in the input schema. The tool description itself adds no parameter information, but since the schema fully documents each field, the baseline is 3. There is no additional semantic enrichment from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Shipping Rate' clearly states the action (create) and the resource (shipping rate). It distinguishes the tool from update/delete rate operations by the verb, though it doesn't explicitly differentiate from siblings with similar naming. The purpose is unambiguous and matches the tool name, which is slightly tautological but still informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, prerequisites (e.g., existing shipping zone, carrier), or how it compares to alternatives like store_update_shipping_rate or store_create_shipping_carrier. There is no context about scenarios that warrant this tool over others. The description is entirely silent on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a create operation (readOnlyHint false, openWorldHint true, idempotentHint false, destructiveHint false). The description adds no additional behavioral details beyond what annotations provide—it does not mention requirements like the altId default, potential duplicate behavior, or any operational consequences. With annotations present, the bar is lower, but the description still fails to provide any supplementary context, earning a minimal score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—just four words—and contains no unnecessary words. It is front-loaded per se, but there is no structure beyond a single phrase. It avoids verbosity and is efficient for an agent to parse, though it misses the opportunity to provide useful context. A concise but complete description would be ideal, so this does not earn a 5 due to lack of content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with required fields and no output schema, this description is inadequate. It does not explain the business meaning of a shipping zone, the expected format of the 'countries' array, or any side effects or prerequisites. The schema provides some field descriptions, but the overall tool context is missing. An agent would struggle to understand when and how to use this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all four parameters (name, altId, altType, countries) with 100% coverage. The description adds no information about parameters, but per the baseline rule, when schema coverage is high, a score of 3 is appropriate even without additional parameter details in the description. The description neither helps nor hurts parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Shipping Zone' states a specific verb and resource, but it is extremely terse. It does not differentiate from sibling tools like store_create_shipping_carrier or store_create_shipping_rate in any way; the only distinction comes from the name itself. It is not vague, but it lacks any additional specification of what a shipping zone is or what it entails, so it barely meets the 'specific verb+resource' bar without added clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any context about prerequisites, side effects, or typical scenarios. It does not say when to use store_create_shipping_zone instead of store_update_shipping_zone or store_create_shipping_rate. There is no misleading information, but also no useful usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds no additional behavioral context—it does not mention pagination, filtering capabilities, return format, or any side effects. Since the description contributes nothing beyond the annotations, it fails to provide extra transparency about what the agent can expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—just three words—but it is more under-specified than concise. It lacks any structure or elaboration that would help an agent understand the tool's purpose or output. A concise description should still be informative; this is merely a fragment that duplicates the tool name. There is no front-loading of key details because there are no details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 optional parameters, no output schema), the description is drastically inadequate. It does not indicate what the returned list contains, how filtering works, or even that this is a paginated response. With no output schema, the description must at least hint at the return structure, but it is entirely absent. An agent has no idea what data fields to expect or how to interpret the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage per the context signals; every parameter (page, sort, sortBy, agentId, etc.) includes a description. The tool description itself adds no parameter information, but per the rubric, when schema coverage is high, the baseline is 3. The description could have added semantics around how parameters interact (e.g., date filters must be paired), but since the schema already explains this, no deduction is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a verb ('List') and a resource ('Call Logs'), making the basic operation evident. However, it does not distinguish this from the sibling tool voice_ai_get_call_log (singular), which could lead to ambiguity about whether this returns a collection vs. a single item. No additional context on the exact scope (e.g., Voice AI call logs) is provided beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as voice_ai_get_call_log or how it fits into the broader Voice AI workflow. The description lacks any context about prerequisites, typical use cases, or exclusions. An agent must infer from the plural name that this lists all call logs, but no explicit direction is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, so the agent knows this is a mutation. The description adds no further behavioral detail (e.g., permanence, impact on ads). It does not contradict annotations, and since annotations cover the core behavior, the description's lack of additional context is acceptable but not helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely minimal, essentially a label rather than a structured sentence. It is not appropriately sized because it omits essential context; this is under-specification rather than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with two parameters and no output schema, the description lacks any mention of consequences, prerequisites, or usage scenarios. It is incomplete and would leave an agent uncertain about side effects and required setup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description says nothing about parameters. Schema coverage is 50%: locationId has a description, but campaignId (required) is undocumented. Since coverage is not high, the description should compensate, but it adds no meaning to either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete campaign' uses a specific verb and resource, clearly indicating a delete operation on a campaign. However, it does not differentiate among sibling tools like ad_manager_fb_delete_ad or ad_manager_fb_delete_adset; the distinction is implicit in the tool name rather than the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no caution about the destructive nature. The description provides no context for selecting this tool or avoiding misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. The description does not add any additional behavioral context beyond the annotation, such as irreversibility, side effects, or what exactly is disconnected. It is consistent with annotations but adds no value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence stating the action. This is appropriately sized for a simple delete operation, and there is no unnecessary verbosity. The action is front-loaded, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and lacks important context for a destructive operation. It does not explain what the deletion entails (e.g., disconnecting the page from the ad account), nor does it indicate any side effects or confirmations. With no output schema, the agent gets no hint about the response. Given the tool's destructive nature, more context is needed to ensure safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for both parameters (pageId and locationId), and schema coverage is 100%. The description adds nothing about parameters, so the baseline of 3 applies per the rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (delete) and resource (page connection). It distinguishes from sibling delete tools by specifying 'page connection' rather than ad, campaign, etc. However, it is terse and does not elaborate on what a 'page connection' entails, so it is clear but not highly descriptive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any exclusions, prerequisites, or conditions. An agent receives no help in deciding when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description is not required to restate safety. However, it adds no behavioral context, such as whether it returns all accessible pages, requires authentication, or has pagination. Given the tool is a read operation, the description should clarify the scope or return behavior but remains silent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just three words, which is under-specified, not concise. It saves space but at the cost of all meaningful content. A concise description should pack essential information into few words; this only restates the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no mention of return format or filters, an agent lacks context on what to expect. The description does not explain that this retrieves pages linked to a Facebook ad account or how locationId and fetchExisting affect results. This is incomplete even for a read tool, though annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters (locationId and fetchExisting) at 100%, so the baseline is 3. The tool description adds nothing beyond this. The fetchExisting schema description is vague ('Fetch existing pages flag') and would benefit from elaboration, but that is a schema issue, not a description failure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Get' and resource 'Facebook pages' are clear, and the tool name also reinforces it. However, it does not specify the scope (e.g., for an ad account) or differentiate from siblings like ad_manager_fb_get_pixels or ad_manager_fb_get_ad_accounts. Still, the purpose is unambiguous on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus other ad_manager_fb_get_* tools. There is no mention of prerequisites, context, or exclusions. An agent must infer usage solely from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict the annotations (readOnlyHint=true, destructiveHint=false), so there's no contradiction. However, it adds no behavioral detail beyond what the annotations already imply (i.e., it's a safe, read-only operation). It fails to state what the tool returns (e.g., a list of keyword ideas, relevance scores, volume data) or how inputs like URL and keywords are used. With annotations covering the safety profile, the description should still provide context about behavior, but it doesn't.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, under-specified phrase. It is not concise in a meaningful way; it omits necessary operational details. The text 'Get keyword ideas' is almost tautological with the tool name, providing no additional structure or information. An effective description would front-load the purpose and then add usage or behavior context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and only a minimal description, the tool is insufficiently documented. An agent cannot determine the return format, the intended use of each parameter, any prerequisites (e.g., Google Ads integration must be set up), or how the tool relates to other keyword-targeting tools. The description leaves too much to inference for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 5 parameters with descriptions (100% coverage). The description offers no additional parameter semantics, but since the schema already documents each parameter, the baseline of 3 applies. The description doesn't need to repeat parameter info, but it could have clarified relationships between URL, keywords, and locations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and a resource ('keyword ideas'), which is a specific action on a resource. However, it doesn't elaborate on what 'keyword ideas' means (e.g., generated from a URL or seed keywords) or how it distinguishes from other Google Ads tools like ad_manager_google_get_target_interests. It is clear but generic, so it earns a 4 rather than a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It doesn't mention ideal scenarios (e.g., when you have a URL to derive keywords), what to do if the URL is missing, or what types of inputs are mutually exclusive. Agents receive no context for selecting this tool over similar Google Ads tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds no behavioral context beyond the verb 'delete.' It does not mention irreversibility, cascading effects, permission requirements, or any other nuance. Since it adds no value over the annotations and remains purely minimal, a score of 2 reflects the lack of additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Delete ad account'), but it simply restates the tool name in a readable form. It adds no additional information that would justify its presence beyond the name. The sentence does not 'earn its place' because it offers no insights about usage, behavior, or parameters. It is not effectively structured for aiding agent decision-making.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, idempotent operation, the description is underspecified. It lacks warning about permanence, the platform context (LinkedIn), and any mention of the optional locationId or its default. Annotations carry the destructive hint, but the description should convey more operational detail (e.g., that the ad account is permanently removed) to fully inform an agent. Given the simple scope and available schema, more context is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema fully documents adAccountId and locationId. The description contributes no parameter-specific information (e.g., how adAccountId is used, defaulting behavior of locationId), but per the rubric the baseline is 3 when schema coverage is high. No extra value is added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (delete) and the resource (ad account). It is not a tautology since it conveys the operation explicitly. However, it does not differentiate from sibling tools that also delete ad accounts (e.g., ad_manager_fb_delete_ad_account, ad_manager_google_delete_ad_account), though the platform is implied by the tool name prefix, so a 4 is appropriate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It does not mention that this is specifically for LinkedIn ad accounts or that other platform-specific delete tools exist. No context about destructive implications or when to avoid use is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety. The description adds no additional behavioral context—it simply repeats the action. It does not mention what gets returned, pagination, error behavior, or any special side effects. Since it adds nothing beyond the annotations, this is a minimal score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is efficient and front-loaded. It has no fluff or redundant information. While it could be more informative, the structure itself is appropriate and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description is still incomplete. It fails to explain what objectKey means, how the association is identified, or what the response contains. It also doesn't clarify when to use this instead of other association lookups. An agent would struggle to determine the exact input format or expected result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only locationId has a description). The description text does not explain either parameter, especially objectKey, which is required and lacks any schema documentation. The description's plural 'keys' contradicts the singular 'objectKey' parameter, adding confusion. No compensation for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('association'), and hints at the lookup method ('by object keys'), which distinguishes it from siblings like associations_get_association_by_id. However, 'object keys' is ambiguous (the schema has a singular 'objectKey' parameter, not multiple keys), and it doesn't clarify what constitutes an object key. Still, it is not a tautology and provides the basic intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention any scenarios, exclusions, or check for required prerequisites. The only usage hint is the locationId parameter's default in the schema, but that's not in the description and doesn't address tool selection. The agent must infer from the name that it's for object-key-based lookups, which is not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is disclosed. The description adds no extra behavioral context, such as pagination, return format, or rate limits. It doesn't contradict the annotations, but it contributes minimal value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff or repetition. It front-loads the core verb and resource, although it omits necessary detail. For a simple read operation, brevity is acceptable, but it borders on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not clarify the meaning of 'blogId' (whether it's a blog container ID or a post ID), nor does it mention pagination or filtering options beyond the schema. With no output schema, agents must infer return structure. The provided annotations reduce the need for safety disclaimers, but the description still leaves critical usage details unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers only 33% of parameters with descriptions (locationId and searchTerm), and the description only mentions Blog ID. It does not explain limit, offset, or status beyond their types and the enum in the schema. With six parameters and low schema coverage, the description fails to compensate for missing semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: get blog posts filtered by a blog ID. It specifies the resource (blog posts) and the key parameter (blog ID), distinguishing it from siblings like blogs_get_blogs or blogs_get_all_categories. However, it doesn't fully clarify whether 'blogId' refers to a blog container or the post itself, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as blogs_get_blogs for fetching blog containers or blogs_create_blog_post for creating posts. It omits any context about prerequisites, typical scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond restating the location ID parameter that is already in the schema. It doesn't mention pagination behavior, whether results are ordered, or what happens with the searchTerm field. Thus, it provides minimal additional 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundancy. However, it is so brief that it omits essential information about behavior and parameters, but the conciseness itself is acceptable, similar to the example of 'update_drive' which scored 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list endpoint with four parameters including pagination and search, this description is inadequate. It doesn't mention what the response contains (no output schema exists), how pagination works, or the role of searchTerm. An agent would struggle to know what to expect or how to properly use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with skip and limit lacking descriptions. The description only mentions locationId, which already has a schema description. It doesn't explain how skip/limit control pagination or how searchTerm affects results. The description fails to compensate for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource combination: 'Get Blogs by Location ID'. It suggests retrieving blogs filtered by a location, which is reasonably specific. However, it doesn't clarify whether it returns a list or a single blog, though the presence of pagination parameters (skip, limit) implies a list. The sibling tool blogs_get_blog_post exists, so this likely retrieves all blogs for a location, but that distinction isn't explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like blogs_get_blog_post, blogs_create_blog_post, or other blog-related tools. The description provides no context about scenarios where filtering by location is appropriate or when other tools should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (a write operation) and openWorldHint=true, but the description does not disclose side effects, return expectations, or validation behavior. It simply states what it does without elaborating on the creation process, required inputs beyond the schema, or potential failures. This is minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is front-loaded with the key action. Though short, it is efficient and appropriately sized for the content it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool—six parameters including an arbitrary rules array, a timezone identifier, and optional calendar IDs—the description is too sparse. It does not explain what constitutes a valid schedule, how rules should be structured, or what the return value is (no output schema). An agent might guess the purpose but lacks enough context to construct correct inputs or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all six parameters with 100% coverage, so the baseline is 3. The description itself adds no parameter-specific elaboration, such as the meaning of 'rules' or the relationship between timezone and locationId. It relies entirely on schema, which is acceptable but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Verb 'create' plus resource 'user availability schedule' clearly indicates the action. It distinguishes from calendars_create_calendar (creates a calendar, not a schedule), though it is not specific about what a schedule entails. The purpose is understandable without being a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like calendars_update_schedule or calendars_add_calendar_to_schedule. There is no mention of prerequisites, edge cases, or why one might choose this over a sibling. The description is purely declarative with no conditional context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral details beyond the verb 'validate'. Annotations indicate readOnlyHint: false (suggesting possible side effects) and openWorldHint: true, but the description doesn't clarify whether the operation is purely a check or if it has side effects, nor what happens on validation failure (e.g., error vs boolean return). The burden of disclosure falls on the description, which is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, 'Validate group slug', which is extremely concise and front-loaded. No superfluous words. However, it is so brief that it sacrifices informative content, but as a matter of conciseness, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the validator returns (e.g., boolean, error list) and what 'valid' means (e.g., slug format, availability). It also doesn't mention any optional inputs like locationId or their role. The tool is underspecified for an agent to use it correctly without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the descriptions are minimal: 'slug' is described as 'Slug' (tautological) and 'locationId' provides a default context. The tool description adds no additional meaning or clarifications about parameter usage, formats, or constraints, so it doesn't enhance the schema beyond what's already there.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('validate') and resource ('group slug'), which is specific enough to distinguish it from CRUD operations like calendars_get_groups or calendars_edit_group. However, it doesn't elaborate on what validation entails (e.g., format check, existence check), leaving some ambiguity about the exact outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives, nor any mention of prerequisites or conditions. The phrase 'validate group slug' implicitly suggests use before creating or editing a group, but this is not stated explicitly, and no alternatives are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. However, the description adds no additional behavioral context, such as irreversibility, what happens to related data, or any side effects. It does not contradict annotations but also does not enhance them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of only two words, which is too terse. It lacks any structure or additional details, making it under-specified rather than appropriately sized. It does not front-load any useful information beyond the bare action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with two required parameters and destructive behavior, the description provides almost no context. It does not explain the relationship between contactId and taskId, error conditions, or what the result of the deletion is. The schema covers parameter names but not the semantics of how they interact. This is inadequate for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the input schema ('Task Id' and 'Contact Id'), so schema coverage is 100%. The description does not add any extra meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Task' is a clear verb+resource combination that unambiguously indicates the operation. It distinguishes from sibling tools like contacts_delete_contact or contacts_delete_note by specifying 'Task'. However, it omits that it deletes a task associated with a specific contact, which is only implied by the tool name and parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool, no mention of prerequisites (e.g., that the taskId must belong to the contactId), no alternatives, and no exclusions. The description simply states the action without any context for selection or invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false (mutable), idempotentHint=true, and destructiveHint=false, so the description does not need to repeat these. However, the description adds no additional behavioral context, such as that attachments replace existing ones (mentioned only in the schema parameter description) or any auth or side-effect details. With annotations covering safety, a minimal description like this adds little value beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence with no fluff. It front-loads the action and resource. However, it is so brief that it borders on under-specification, lacking any structural context that would guide an agent. Still, for conciseness alone, it is appropriately sized and well-front-loaded, so a 4 is reasonable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no nested objects, no output schema), the description should still explain key contextual details, such as that it operates on an existing message and that attachments replace existing ones. Neither is stated in the description; the schema mentions replacement but not that it's for existing messages. The description is incomplete for an agent to fully understand when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: messageId is described as 'Message Id' and attachments as 'Array of attachment URLs to set on the message (replaces existing). Maximum 5 URLs.' The description does not add any meaning beyond the schema, so a baseline of 3 is appropriate. The schema already communicates the semantics effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add message attachments' clearly states the action (add) and the resource (message attachments), matching the tool name. It is not a tautology and conveys the core purpose. However, it does not differentiate this tool from siblings like 'conversations_send_a_new_message' which might also include attachments, so it loses a point for not distinguishing the specific use case (attaching to an existing message).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., message must exist), no exclusions, and no mention of related tools like 'conversations_add_an_inbound_message' or 'conversations_send_a_new_message'. The agent receives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the operation's safety profile. The description adds no additional behavioral details, such as what a recording actually represents (audio/video), the format of the response (URL, binary, etc.), or behavior when no recording exists. Since annotations carry the informational load and the description contributes nothing beyond the basic action, the score is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no fluff, but it is under-specified rather than concise. It merely restates the tool name ('Get Recording by Message ID' matches conversations_get_message_recording) without adding substantive detail. It lacks front-loaded, distinguishing information that would help an agent decide to use it. The brevity is not an asset because it sacrifices meaningful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters and no output schema, the description should at least hint at what the response contains (e.g., a URL to the recording, a file, or raw audio). It gives no indication of the return value, leaving the agent guessing. The annotations provide safety context but not operational completeness. This is a significant gap for an agent to correctly interpret the tool's outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters with 100% description coverage: messageId is described as 'Message ID as string' and locationId has a clear description including a default value. The tool description itself adds no parameter semantics beyond what the schema already provides. Per the rubric, with high schema coverage the baseline is 3, and there is no additional value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Recording by Message ID' clearly states the action (get) and the resource (recording) keyed by message ID. It is specific enough to understand the core function. However, it does not differentiate itself from the sibling tools like conversations_get_message_transcription or conversations_download_message_transcription, which also retrieve message-associated artifacts. The name itself provides most of the clarity, so the description adds little beyond a restatement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as getting a transcription or downloading a recording. No context is given about scenarios where this tool is preferred, prerequisites, or how it relates to other conversations_* tools. An agent would have to infer usage solely from the name and parameter schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which already convey that this is a safe, read-only operation. The description 'Get Forms Submissions' is consistent with these but adds no behavioral context beyond what the annotations already state. It doesn't mention pagination, defaults, or any side effects, so it provides minimal additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words, which is extremely short. While it is concise, it is not appropriately sized for a tool with 7 parameters and no output schema. It fails to convey key information about filtering, pagination, or date ranges. It reads more like a tautology than a useful explanation, offering negligible value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 optional parameters, 100% schema coverage but no output schema), the description is severely lacking. It does not explain what the submissions look like, how the date filters work, or any usage context. The schema covers parameter documentation, but the description provides no thematic overview, leaving the agent without a high-level understanding of the tool's capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 7 parameters, including defaults like 'Page No. By default it will be 1' and 'Limit Per Page records count. will allow maximum up to 100'. The description itself does not elaborate on any parameters, but the schema already does the heavy lifting. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Forms Submissions' clearly states the verb (get) and the resource (forms submissions), which is unambiguous. However, it does not differentiate from the sibling tool 'forms_get_forms', which retrieves the forms themselves; a user could confuse which tool to use. The name and description are nearly identical in information content, so it's clear but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'forms_get_forms' or 'surveys_get_surveys_submissions'. The description does not mention any preconditions, contexts, or exclusions. An agent would have no idea if this is the right tool for a given scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description has a low bar, but it adds no behavioral context such as what settings are returned or any operational implications. No contradiction, but zero added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and to the point, but it is under-specified. It earns a 4 for being appropriately short for a simple getter, though it could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and that annotations cover the read-only nature, the description is minimally adequate. However, it does not explain what settings are returned or any edge cases, so it lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents both parameters. The description adds nothing beyond that, which is acceptable per the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource, but it restates the tool name without adding specificity about what 'Invoice Settings' encompasses. It distinguishes from siblings because no other tool targets invoice settings, but it fails to define the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other invoice-related tools. The description provides no context on prerequisites, alternatives, or intended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which already communicate that this is a non-destructive, idempotent write operation. The description adds no additional behavioral context such as what gets overwritten, required permissions, or side effects. Since the description carries none of the transparency burden, it barely adds value beyond the annotations, resulting in a low score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence with no fluff. It is front-loaded with the main action and resource. While it could be longer to provide more context, it is efficient and easy to parse, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a large schema (17 parameters, 6 required) and nested objects, the description gives no overall context about the operation, e.g., that it modifies an existing template, that templateId is essential, or how the fields interrelate. The lack of an output schema and the complexity of the tool mean the description is far from complete for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (88%), so most parameters already have descriptions in the schema. The tool description itself adds no parameter-related meaning, but the schema handles it. With such high coverage, a baseline score of 3 is appropriate; the description does not need to repeat parameter details and does not add any cross-parameter insights either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Estimate Template' clearly states a specific verb (update) and resource (estimate template), distinguishing it from related tools like invoices_create_estimate_template and invoices_delete_estimate_template. However, it lacks any detail about what fields can be updated or the context of the operation, so it is clear but minimally informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing an existing template), the difference from creating or listing templates, or any conditions under which this tool is preferred. An agent receives zero context to decide between this and the many sibling invoice/estimate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' adds no new behavioral information. The description does not disclose any additional side effects, permanence of deletion, or whether the operation is reversible. With annotations present, the bar for adding context is lower, but this description fails to add any context beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is under-specified, consisting of only three words. While concise, it omits critical context and is more of a minimal placeholder than a properly sized description. It lacks any structure or front-loading of key information, making it inadequate for an agent to fully understand the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description should explain the effect, required inputs, and any relevant dependencies. It does not mention that trained URL IDs come from a specific endpoint, how the knowledge base ID is used, or what the operation returns. The schema provides some context but the description leaves significant gaps, making it incomplete for an agent to call correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the schema. The description adds no information about the parameters. According to the calibration rule, with high schema coverage, a score of 3 is appropriate even without param details in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Delete') and resource ('trained pages'), which accurately reflects the tool's function. It is not a tautology because it uses 'trained pages' instead of repeating the tool name. However, it does not explicitly mention the knowledge base scope or differentiate from sibling tools like knowledge_base_delete_knowledge_base, though the tool name itself provides some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions for use, or exclusions. The usage context is only implied by the tool name and required parameters. This is a significant gap since a caller needs to know this is for removing specific trained URLs from a knowledge base, not for other deletion operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context beyond that—no mention of what the response contains, whether the resource might not exist, error handling, or any rate limits. Since the description adds no value beyond annotations, it fails to compensate for the absence of an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just a single sentence that essentially restates the tool name ('Get Recurring Task By Id' vs 'locations_get_recurring_task_by_id'). It is concise, but it does not earn its place—it adds no information beyond what the name already conveys. Effective conciseness would involve front-loading useful constraints or context, which is absent here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters and no output schema, the description is very sparse. It does not explain what a recurring task is, what the response looks like, or any related context. Given the lack of an output schema and the existence of sibling tools for task management, more context (e.g., typical usage or return format) is expected for completeness, but none is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage: id is described as 'Recurring Task Id' and locationId includes a default behavior. The tool description itself doesn't add any parameter details, but because schema coverage is complete, the baseline of 3 applies. The description offers no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get Recurring Task By Id' which clearly identifies the action (get) and resource (recurring task) with a specific identifier. It is unambiguous and not a tautology because it adds the verb 'Get' and the qualifier 'By Id', though it does not explicitly differentiate from sibling tools like locations_task_search or locations_get_tag_by_id. It is clear but lacks explicit sibling contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this should be used when an id is already known, or that for searching/filtering one should use locations_task_search. There is no mention of exclusions or contexts, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint, openWorldHint, and idempotentHint, but the description adds no behavioral detail beyond that. It does not mention permanence, cascading effects, or required permissions. Since it adds no value beyond annotations, it scores low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two words, which is under-specified rather than appropriately concise. It lacks necessary context that would make it useful, so it does not earn a high score for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive operation with openWorldHint, the description is insufficiently complete. It does not explain implications like data loss, scope, or external effects, and there is no output schema to clarify behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single 'id' parameter with 'Opportunity Id', providing 100% coverage. The description adds no additional meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Opportunity' clearly states a specific verb and resource, and the tool name reinforces it. However, it does not differentiate from other delete tools beyond the resource name, and there is no added context about what an opportunity is or scope. It is clear but minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, when not to use it, or any prerequisites or side effects. It simply states the action with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, covering the safety profile. The description adds no context beyond the literal 'Delete Coupon', such as irreversibility, impact on associated data, or permission requirements. It neither contradicts nor enriches 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is undeniably concise, but it suffers from under-specification rather than effective brevity. It lacks any structural guidance or explanatory context, making it more of a label than a useful description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description is incomplete. It does not mention what happens after deletion, whether the action is reversible, or any failure modes. Even though the tool is simple, the lack of side-effect context makes it insufficient for an agent to fully anticipate the behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters have descriptions), so the schema fully documents parameter meaning. The description itself provides no additional parameter semantics, which matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Coupon' clearly states a specific verb (Delete) and resource (Coupon), unambiguously distinguishing it from sibling tools like payments_create_coupon, payments_get_coupon, and payments_update_coupon. Although terse, the purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this deletion tool versus related tools such as payments_update_coupon or payments_list_coupons. There is no mention of prerequisites, side effects, or scenarios where deletion is appropriate, leaving the agent to infer usage from the operation type alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Deleting' is consistent but adds no extra behavioral context. It does not mention that deletion is permanent, that it may affect associated orders or subscriptions, or that it is idempotent (despite idempotentHint=true). The description adds no value beyond what annotations already 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase with no fluff. It is front-loaded with the action. However, it is so brief that it borders on under-specification, but for a tool with minimal parameters, the brevity is not distracting. It earns a 4 for efficiency, though not a 5 because it omits essential context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with no output schema, the description should explain side effects, reversibility, and what the agent can expect. It does not mention that deletion is irreversible, nor does it indicate what happens to related data (e.g., orders, subscriptions). The description also fails to state that the integration must exist or that deletion may fail if in use. This leaves the agent with insufficient guidance for a critical operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single parameter (locationId) with a clear description and default behavior, and schema coverage is 100%. The description itself adds no parameter-level detail, which is acceptable given the schema's completeness. Baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Deleting') and the resource ('an existing integration'). While it doesn't explicitly mention 'payments', the tool name and sibling context make it clear this is for payment integrations. It distinguishes from other delete tools by resource, though not by scope. It's specific enough for an agent to grasp the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, what conditions apply, or when to prefer alternatives. There is no mention of prerequisites, such as needing an integration ID, or any warning about deleting an integration in active use. The agent is left without context on appropriate invocation scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context, such as expected response format, authentication requirements, or any side effects. It simply restates the action without enriching what the annotations already tell us. No contradiction, but no added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, but it is under-specified. It does not earn its place because it adds no value beyond the tool name. It is not verbose, but it is too brief to be considered appropriately sized. A one-line description that merely restates the name does not satisfy the requirement for front-loading useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema), the description is incomplete. It does not explain what the tool returns, when it might fail, or any contextual nuances. The schema covers parameter meanings, but the description fails to compensate for the lack of an output schema or to provide any operational context. For a simple get tool, this is still insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are described in the schema, including transactionId, altId, altType, and locationId. The description adds no meaning beyond what the schema already provides. Per the rubric, with high schema coverage, the baseline is 3, and since the description contributes nothing extra, it remains at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Transaction by ID' clearly states the action (get) and the resource (transaction by ID), making the purpose understandable. However, it does not differentiate from sibling tools like payments_get_order_by_id or payments_get_subscription_by_id, and it omits context about what constitutes a 'transaction' in this domain. It is clear but not specific enough to distinguish among similar get-by-ID tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternative tools. There is no mention of conditions, exclusions, or alternatives. An agent would have no indication of why to choose this over other payments-related get operations, such as payments_get_order_by_id. This is a complete absence of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no behavioral details such as pagination behavior, sorting, filtering, or what exactly constitutes an 'order note', so it provides no additional 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal but not intentionally concise; it omits essential explanatory content. While it is not verbose, the single phrase is underspecified rather than efficiently worded, flagging it as under-specification rather than good conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a terse description, the tool lacks clarity on what is returned, how notes are ordered, or any limitations. For an agent to decide if this tool meets its needs, the description is insufficient—more context is expected for a listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (altId, altType, orderId). The description does not add any parameter-related information, so it falls to the baseline of 3, as the schema already handles the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Order Notes' uses a specific verb with a clear resource, stating exactly what the tool does. It does not name any sibling tools for differentiation, but the core purpose is unambiguous without needing further context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like payments_list_orders or payments_get_order_by_id. There is no mention of prerequisites, exclusions, or preferred scenarios, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context—no mention of pagination (limit/offset), filtering capabilities, or what a successful response contains. It provides zero 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short—two words—and while it contains no fluff, it is under-specified rather than concise. It lacks structure, front-loading of key constraints (like required params), and any instructional content. It reads like a placeholder rather than a deliberate summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters and 2 required, the description offers no explanation of the required altId/altType, no mention of pagination semantics, and no guidance on filters like search or paymentMode. There is no output schema, and the description doesn't clarify the return shape. An agent would find the schema alone insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a terse description. The tool description 'List Transactions' adds no extra meaning to the parameters, meeting the baseline for full schema coverage. No further elaboration is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description 'List Transactions' clearly states the verb (List) and resource (Transactions), and distinguishes it from single-record tools like payments_get_transaction_by_id. It could be more specific about scoping (e.g., by altId), but the basic purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like payments_list_orders, payments_list_subscriptions, or payments_get_transaction_by_id. The required parameters altId/altType are not explained in the description, leaving the agent to infer usage from the schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the token-level requirement, which is useful context beyond annotations. However, it doesn't describe pagination, error behavior, or response format, so it adds limited behavioral value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and includes a critical access constraint. It is not verbose and every word adds some value, though it could be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple GET tool with two required parameters but no output schema and no parameter descriptions. The description only provides the action and token requirement, missing crucial details about parameters, pagination, and response format. For an agent to call this correctly, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% – parameters `companyId` and `page` have no descriptions in the schema, and the description doesn't explain them at all. The tool description fails to compensate for the lack of parameter documentation, leaving agents without any guidance on what values to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get SaaS Locations' – a specific verb and resource. It also adds an important access requirement (agency-level token). However, it doesn't differentiate from similar sibling tools like saas_api_locations or the deprecated variant, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite (agency-level token) but no explicit guidance on when to use this tool vs alternatives like saas_api_locations or the deprecated version. It doesn't mention exclusions or alternative tools, so the usage context is incomplete.
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?
The description says 'Delete', which implies a destructive operation, but the annotations set destructiveHint=false, indicating the tool is not destructive. This is a direct contradiction. The description also fails to disclose any side effects, reversibility, or permission 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase with no wasted words. It is efficiently front-loaded and to the point, though it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk delete operation with no output schema and minimal annotation, the description is inadequate. It does not mention what happens to the posts, whether deletion is permanent, what the response contains, or any prerequisites. The contradictory annotation further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented, but the descriptions are vague ('Requested Results' for postIds). The tool description adds no additional parameter meaning, relying entirely on the schema. Baseline 3 is appropriate given high coverage, though the schema descriptions themselves are weak.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('Social Planner Posts') and implies bulk operation via the name and description. It clearly identifies the action but does not explicitly differentiate from siblings like social_media_posting_delete_post, though the 'Bulk' prefix provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., singular delete_post, delete_csv_post). The description offers no context about selection criteria or prerequisites, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the basic safety profile is known. However, the description adds no behavioral context beyond the action itself, such as permanence, platform-specific behavior, or 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase 'Delete Post', which is concise but under-specified. It lacks any explanatory content that would help an agent understand usage, making it too sparse to be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description is minimal. It does not explain the deletion scope, permanence, or any associated consequences beyond the action. The annotations cover safety, but the description fails to provide additional necessary context for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (id and locationId) with descriptions, achieving 100% coverage. The description adds no additional parameter meaning, but since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Post' clearly states the verb and resource, matching the tool name and indicating a single post deletion. It distinguishes from bulk delete and other delete tools by its singular focus, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like bulk delete or other deletion tools. The description does not mention any context, exclusions, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds no extra behavioral context (e.g., that it returns an OAuth URL or requires user interaction), but it does not contradict the annotations. Since the annotations carry the safety profile, the description's minimalism is acceptable but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single five-word sentence, but it is under-specified rather than concisely informative. Essential information about parameters, return value, and usage is omitted. This is not effective conciseness but rather a lack of necessary content, penalizing the structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and no output schema, the definition is incomplete. It fails to explain parameter semantics, what the OAuth flow returns, or what the agent should do with the result. The absence of usage guidelines and behavioral detail makes it difficult for an agent to invoke it correctly, especially given the large number of sibling OAuth tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are 100% present but superficial: 'Page', 'User Id', 'Reconnect', and 'Location Id' provide no semantic context. The tool description does not explain these parameters, leaving the agent to guess what 'page' or 'reconnect' mean. Even though schema coverage is high, the quality is low, and the description fails to compensate, so the score is below the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Starts OAuth For Tiktok Account' clearly specifies the action (starts OAuth) and the resource (TikTok account). It distinguishes itself from sibling OAuth start tools by naming the platform, so an agent can select it when TikTok is the target. However, it lacks detail on what OAuth entails (e.g., generating a redirect URL), which would further clarify 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives like start_facebook_oauth or start_instagram_oauth. It does not state prerequisites (e.g., having a TikTok business account) or scenarios where this should be avoided. The description merely states the action without any contextual or exclusionary information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, which cover the key behavioral traits. However, the description adds no additional context beyond repeating the action. It does not mention that deletion is permanent, that it affects only the specified rate, or any side effects. Since the description adds no value beyond what annotations already provide, the score is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single phrase with no extraneous words. It is well-structured in the sense of being brief and to the point. However, it is so sparse that it might be considered under-specification rather than efficient writing, but given the tool's simple nature, it earns a pass for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with two required parameters and no output schema, the description is incomplete. It does not explain what happens on success (e.g., returns success/failure), whether the rate must exist first, or any consequences of deletion. The annotations cover destructiveness, but the description lacks the necessary contextual detail for an agent to confidently invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents each parameter. The description itself adds no parameter information. With high coverage, the baseline is 3 because the schema carries the burden. The description does not compensate or clarify anything beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete shipping rate' clearly states the action (delete) and the resource (shipping rate). It is specific enough to convey the core purpose, though it does not differentiate from sibling operations like store_delete_shipping_zone or store_update_shipping_rate. It adds no detail about the context (e.g., within a shipping zone), but the verb+resource pairing is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, conditions, or exclusions. With many sibling store tools, there is no differentiation to help an agent decide between delete, update, or list operations. This is a complete absence of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write), destructiveHint=false (non-destructive), idempotentHint=true, and openWorldHint=true. The description merely says 'Update Shipping Carrier' and does not disclose any additional behavioral traits such as whether it replaces all fields or only provided ones, what happens to unmentioned fields, or any side effects. It adds nothing beyond the annotations and the action itself, failing to meet the bar for a mutation tool where the description should clarify partial vs. full replacement or preconditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase 'Update Shipping Carrier'—extremely concise but under-specified. It effectively restates the tool name and provides no additional value, so it does not 'earn its place.' While brevity is a virtue, this is too minimal to be informative, crossing into under-specification rather than concise clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter update tool with no output schema, the description is drastically incomplete. It does not clarify whether the update is partial or full, whether the carrier must exist, what happens to omitted fields, or any operational context. Even with full schema coverage, the description fails to provide the operational semantics 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 7 parameters fully documented in the input schema, including defaults for altId and altType and the requirement for shippingCarrierId. The description adds no parameter-specific information, so it does not compensate for any gaps. Baseline of 3 is appropriate because the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'Shipping Carrier', so the primary action and object are unambiguous. It distinguishes itself from siblings like store_create_shipping_carrier and store_delete_shipping_carrier by the verb, but it adds no additional detail about what aspects of the carrier can be updated or its scope. The purpose is clear, though it relies on the name and schema for specifics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not state that the carrier must already exist, whether it is a partial or full update, or how it differs from store_create_shipping_carrier or store_update_shipping_rate. The description offers no context for selection among related store tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no behavioral details beyond that, such as pagination behavior, default page size, or what happens with the query parameter. With no extra transparency, this is a minimal addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse ('List Agents') and functions more like a title than a description. It is concise, but it lacks structure and doesn't earn its place as a full description. It provides no additional context or elaboration, which makes it under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a list operation with a complex environment (openWorldHint), the description omits important details such as what the return payload looks like, whether pagination is supported beyond the page/pageSize params, and how 'query' and 'locationId' affect results. With no output schema and minimal description, an agent lacks sufficient context to correctly invoke and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all four parameters (page, query, pageSize, locationId). The description itself ('List Agents') adds no parameter semantics beyond what the schema already provides. Since the schema carries the full burden, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Agents' clearly states a specific verb (List) and resource (Agents). It distinguishes from the sibling voice_ai_get_agent (singular) which implies fetching a single agent, so the purpose is understandable. However, it doesn't explicitly mention that it lists all agents or support filtering, which could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of when to choose this over voice_ai_get_agent or other listing tools like agent_studio_get_agents. The only implicit cue is the name itself, but no explicit context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds nothing beyond the bare action – no mention of side effects, idempotency implications, or what happens if a member already exists. It fails to disclose any behavioral traits beyond what the annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it essentially restates the tool name with minimal added value. It is not front-loaded with any useful context beyond the action itself, so while concise, it is not particularly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with 4 parameters and no output schema, this description is incomplete. It does not explain return values, error conditions, or edge cases like duplicate members. An agent requires more context to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 4 parameters, so the schema already documents each field. The description adds no extra meaning about parameter semantics, relationships, or usage details. This is the baseline 3 because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add custom audience member' – a specific verb and resource. However, it does not differentiate from sibling tools like ad_manager_fb_remove_custom_audience_member or ad_manager_fb_batch_update_audience_members, so it misses the distinction that would make it a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context like 'use batch update for multiple members'. The description offers no usage direction at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds no behavioral context beyond that—it doesn't explain consequences (e.g., permanent removal) or any side effects. It fails to enrich the agent's understanding of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but is essentially a restatement of the tool name, providing no additional structure or front-loaded value. It's not verbose, but it's not optimally structured to convey useful information beyond the obvious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive operation, the description should explain when it's appropriate (e.g., removing a contact from a custom audience) and any implications. It doesn't mention required identifiers beyond what the schema lists, nor any validation or error conditions. For a destructive tool, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are described in the schema with adequate detail, so schema coverage is 100%. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Remove custom audience member'. This distinguishes it from sibling tools like add_custom_audience_member and batch_update_audience_members. However, it lacks context about scope (e.g., which audience types) and is essentially a restatement of the tool name, so it's clear but not enhanced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., needing an existing audience member) or when a different tool like batch_update might be preferable. It simply states the action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which covers safety. The description adds no additional behavioral context (e.g., pagination, scoping, or what data is returned). It neither contradicts the annotations nor provides extra transparency beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and front-loaded. However, it is too terse to add any usable nuance, so while it earns full marks for brevity, it lacks the substance that would make it well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of numerous sibling tools with similar purposes, and no output schema, this description is insufficient. It does not clarify what the returned list contains, how account types map to parameters, or how this differs from related tools like ad_manager_google_get_ad_account_details. An agent would struggle to choose this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% – both 'type' and 'locationId' have descriptive text in the schema. The description itself adds nothing about parameters, but since the schema fully covers them, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Get Google ad accounts' – a specific verb and object. However, it does nothing to distinguish itself from closely related siblings like ad_manager_google_get_ad_account_details or ad_manager_fb_get_ad_accounts, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many similar ad account retrieval tools. No context about account type selection, default behavior, or when to prefer this over get_ad_account_details. This is essentially a bare statement with no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the verb 'Get'—it does not mention what fields are returned, what happens if the adId is invalid, or whether the result is a single object or a list. Since it adds nothing over the annotations, a score of 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single phrase with no wasted words—but this extreme brevity sacrifices utility. It is not front-loaded with any meaningful detail beyond the verb and resource. It is structured acceptably but under-specified, so it earns a middling score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple getter with 2 parameters and 100% schema coverage, so the description should clarify what a 'campaign group' is and what the tool returns. Here it only repeats the tool name without elaboration. It also fails to note that this is a LinkedIn-specific tool (implied by 'li' in the name) or how it differs from reporting tools. An agent would have to guess at essential context, making this incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (adId and locationId) are already documented with descriptions. The tool description does not add any extra meaning or usage hints beyond what the schema provides. Baseline 3 is correct as the schema does the heavy lifting, and no additional clarity is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('ad campaign group'), making it clear what the tool does. However, it does not differentiate it from sibling tools like ad_manager_li_get_campaign_group_reporting or ad_manager_li_get_ad_account_details, so an agent might confuse them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, use cases, or distinctions from similar 'get' tools in the ad_manager_li family. An agent would need to infer usage from the tool name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the basic safety profile. The description adds nothing beyond the bare verb, so it does not enhance behavioral transparency. 'Upsert' implies create-or-update, which aligns with idempotentHint, and there is no contradiction. Given the annotations, a baseline score is appropriate, but the description fails to add context like side effects or async behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource. However, it is so terse that it sacrifices substance for brevity, though for what it does state, it is efficient and structured well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters, nested objects, and no output schema, this description is grossly inadequate. There is no explanation of required fields (all optional, but what does that mean?), how to identify an existing campaign group (via id or adCampaignGroupId?), or the significance of budget, objectiveType, and publishingStatus. An agent cannot correctly construct a call without additional external knowledge, making the description effectively useless for this complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 8%, with only locationId and schedule dates having descriptions. The tool has 13 parameters including enums and nested objects, yet the description provides zero explanation of key fields like id, adCampaignGroupId, budget, or objectiveType. Since coverage is low, the description must compensate but does not, leaving agents to infer semantics from the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Upsert' and the resource 'ad campaign group', which clearly indicates create-or-update functionality. However, it does not differentiate from sibling tools like ad_manager_li_publish_campaign_group or the FB/Google upsert campaign tools, though the name itself provides some distinction. The purpose is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is provided. The description gives no indication of when to use this tool versus alternatives such as ad_manager_li_get_campaign_group for retrieval or ad_manager_li_publish_campaign_group for publishing. There is no mention of prerequisites like requiring an existing integration or ad account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond the schema—it implies a retrieval operation but does not disclose pagination behavior, response format, or any limitations. Since annotations carry the safety burden, the description's lack of additional detail is acceptable but not exemplary; a 3 reflects that it adds limited 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it lacks structured exposition. It front-loads the key action and resource, but provides no additional structure like bullet points or clear parameter explanations. It is appropriately short but at the expense of necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the tool returns and any relevant context. It does not describe the response structure, pagination, or the nature of 'relations'. Given the tool has 5 parameters (3 required) and is a read operation, the description is too sparse to fully equip an agent to call it correctly without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%: only locationId and associationIds have descriptions in the schema, while skip, limit, and recordId are undocumented. The description mentions 'record Id' but does not explain the meaning or usage of skip, limit, or associationIds. It fails to compensate for the low schema coverage, leaving agents uncertain about required and optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action (Get) and resource (relations) with a scope qualifier (by record Id). This distinguishes it from sibling association tools like associations_get_association_by_id which fetch a single association, and associations_get_association_by_object_keys which uses object keys rather than a record ID. The verb and resource are specific, though the term 'relations' could be more explicit about what it represents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The sibling list includes several association-related tools, but the description does not mention conditions, exclusions, or routing logic. An agent would have to infer from the name alone that this retrieves relations when you have a record ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's only addition is the word 'Update'. It doesn't disclose that only provided fields are changed, that the board must exist, or what the response looks like. No extra behavioral context beyond annotations is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise. However, it is under-specified rather than efficient – it could include key usage hints without becoming verbose. It earns its place but doesn't leverage the space to add value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool, the description is far too thin. It doesn't clarify partial vs full update, the defaulting of locationId (which is noted in the schema but not here), or any return value. Without an output schema, the description should at least hint at the response. This is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter (id, name, fonts, etc.). The description adds nothing about parameters, which is acceptable per the high coverage baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a Brand Board' clearly states the action (update) and resource (Brand Board). It is unambiguous and distinguishes from create/delete/get siblings by name, but it does not specify which fields can be updated or that it's a partial update, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It doesn't mention that it's for existing boards, that 'create' should be used for new ones, or that 'get' retrieves before updating. The agent must infer usage from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no extra behavioral context such as potential return formats, errors, or limitations. It merely restates the purpose without enriching 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the purpose. It is appropriately sized, front-loaded, and contains no extraneous information, earning a perfect score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description is minimally adequate but lacks necessary context. It does not specify what 'user availability schedule' entails, what the return value looks like, or any operational details, leaving an agent partially informed for a read operation without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as the parameter 'id' has a clear description. The tool description does not add any parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate given that the schema fully documents the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get user availability schedule' uses a specific verb and resource, clearly indicating a read operation for a schedule. It is distinct enough from generic tools but does not explicitly differentiate from sibling calendar tools like calendars_get_calendar or calendars_get_slots, so it lacks sibling disambiguation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios, exclusions, or relationships to other calendar tools, leaving an agent without context for selection among many similar siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds no behavioral context beyond that: it doesn't explain what side effects occur (e.g., creating a resumable upload URL), whether authentication is needed, or what happens if the upload isn't completed. Since the annotations cover safety, the description adds minimal value here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only six words, which is concise and front-loaded, but it's too sparse to provide meaningful context. It reads as a fragment rather than a structured explanation. It earns a 3 because it's not verbose, but it lacks the substance that would make it genuinely helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool is part of a multi-step upload process (initiate then complete), but the description doesn't mention the follow-up step or what the response contains (e.g., an upload URL or ID). With six parameters and no output schema, the description should explain the flow and any dependencies. It falls short, leaving the agent without critical information 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all six parameters (channel, fileSize, filename, locationId, contentType, conversationId). The description adds no parameter-specific details. Baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Initiate') and resource ('file upload to GCS'), making the core action clear. However, it does not explicitly differentiate from the sibling tool conversations_complete_file_upload, which is the logical follow-up step. The name itself hints at a two-step process, but the description doesn't clarify the relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives like conversations_complete_file_upload or conversations_add_message_attachments. The description doesn't mention the prerequisite of having a conversation ID or the requirement to call a completion step after initiating. The agent is left to infer the workflow from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond the action itself. While annotations cover safety (readOnlyHint, destructiveHint), the description does not disclose what 'preview' produces (e.g., rendered content, a URL, a file) or any side effects. It merely restates the name, adding minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief ('Preview Estimate Template'), which is concise but lacks structured detail. It is a noun phrase rather than a full sentence, and while it wastes no words, it also provides no context, making it more under-specified than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description should explain what the preview returns or how it is presented. It does not, leaving the agent uncertain about the result format. Given the tool's simplicity and existing annotations, additional context about the preview output would be expected but is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all three parameters (templateId, altId, altType) with descriptions and defaults, so schema coverage is 100%. The description adds nothing about parameters, but the baseline of 3 applies because the schema adequately handles parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Preview') and resource ('Estimate Template'), which conveys the core action. It is distinct from sibling tools like invoices_create_estimate_template or invoices_list_estimate_templates, but it does not explicitly differentiate itself, relying on the verb 'preview' to imply read-only behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as listing or creating estimate templates. There is no mention of use cases, prerequisites, or conditions that would lead an agent to select this tool, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, implying a mutation that is not destructive. The description simply says 'update' which aligns but adds no further behavioral context. It does not disclose whether the entire configuration is replaced or only partially updated, what happens to existing settings, whether it is idempotent (idempotentHint=false is not elaborated), or any side effects. Since annotations are minimal, the description carries the burden but fails to provide it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. However, it is so terse that it borders on under-specification rather than effective conciseness. Every word is necessary but the value added is minimal. A slightly more informative phrasing without excessive length would improve this dimension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested parameter structure (lateFeesConfiguration with nested objects for grace, frequency, maxLateFees) and no output schema. The description does not explain how these configurations are applied, what the required fields mean in context, or what the response would indicate (e.g., success or failure). Given the complexity, the description is insufficient for an agent to call this tool correctly without opening the schema and making assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters having descriptions. The description adds no extra semantics beyond what the schema already states. For nested objects like 'grace' and 'maxLateFees' which are only described as 'Late Fees Grace' and 'Max late fees payable' with no structure, the description could have clarified their format, but it doesn't. Baseline 3 is appropriate as the schema does most of the work, but the description misses an opportunity to clarify complex nested parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update invoice late fees configuration' clearly states the action (update) and the resource (invoice late fees configuration). It is distinguishably about invoices rather than invoice templates, but it does not explicitly differentiate from the sibling tool 'invoices_update_invoice_template_late_fees_configuration' which could cause confusion if the agent doesn't notice the 'invoice' vs 'invoice_template' distinction in the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like invoice template late fees configuration, nor does it mention any prerequisites (e.g., invoice must exist, configuration must be active). An agent has to infer usage solely from the parameter names, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond the verb 'void'. It does not explain what voiding means, whether it is reversible, what side effects occur, or what happens to the invoice's status. With annotations present, the description still falls short of disclosing meaningful behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), which is efficient but under-specifies. It is front-loaded in the sense that it conveys the core action immediately, but it lacks any elaboration on usage or context. Conciseness is appropriate, but the structure is minimal to the point of being unhelpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema, the description does not explain the effects of voiding an invoice, any state changes, or expected outcomes. An agent would not know if the operation is reversible, whether the invoice becomes unmodifiable, or what response to expect. The minimal description is insufficient for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters, including the required invoiceId and optional altId/altType with defaulting behavior. The description 'Void invoice' adds no parameter-level semantics, so it relies entirely on the schema. This meets the baseline for high schema coverage but adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Void invoice' clearly states the action (void) and the resource (invoice), distinguishing it from sibling tools like invoices_delete_invoice and invoices_update_invoice via the specific verb. However, it does not explicitly contrast with those alternatives, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as delete or update. There are no prerequisites, conditions, or exclusions mentioned, so an agent cannot determine when voiding is the appropriate operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, conveying that this is a safe, repeatable update. The description adds nothing beyond the word 'update', which merely restates the mutation. No contradiction exists, but no additional behavioral context (e.g., partial update semantics, return behavior) is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and front-loaded. However, it is so minimal that it borders on under-specification. It is not verbose, but it also does not earn its place by conveying necessary information beyond the obvious.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and a terse description. An agent lacks context on return values, partial update behavior, and when to prefer this tool over the identically named sibling 'knowledge_base_update'. The definition is incomplete for a newcomer and relies heavily on the schema and sibling names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has descriptions for 'name' and 'description' (67% coverage), but the description itself adds no parameter semantics. It does not explain the 'id' parameter or clarify how the fields interact. The description fails to compensate for the missing id description or provide any added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Update a knowledge base'. It distinguishes from create/delete operations, but there is a sibling tool 'knowledge_base_update' with an identical purpose, so it does not differentiate that specific alternative. The core purpose is unambiguous, but the redundancy slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus the similarly named 'knowledge_base_update' or other knowledge base tools. There is no mention of prerequisites, exclusions, or alternative recommendations, leaving the agent to guess which update tool to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat safety, but it adds no additional behavioral context. It doesn't mention what the response contains or any special behaviors such as field filtering or defaults. Since the description adds nothing beyond annotations, it scores low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no wasted words, which is good, but it lacks any structure or additional information. It's a minimal label rather than a helpful description, so while concise, it doesn't add value beyond the name. It is not verbose but under-specifies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description is insufficient. It doesn't explain what the operation returns (e.g., a link object) or any usage context, such as how the locationId default works in practice. Given the annotations cover safety but not functionality, the description should at least mention that it retrieves a link's details, but it doesn't. This leaves the agent without key information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both linkId and locationId have descriptions in the schema, with locationId noting it defaults to GHL_LOCATION_ID when omitted. The description 'Get Link by ID' adds nothing about parameters, and the schema already explains them fully. Baseline is 3 because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a resource 'Link' and an identifier 'ID', clearly indicating it fetches a single link by its ID. However, it doesn't explicitly distinguish itself from list-oriented tools like links_get_links, though the name partially conveys that. It is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that it should be used when a specific link ID is known, nor does it reference other link-related tools like links_get_links or links_search_trigger_links. There is no context for selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. However, the description adds no behavioral context beyond the name, such as return format, pagination behavior, or how search results are scoped. It fails to describe the search semantics or any quirks beyond what the annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, consisting of a single sentence. However, it is so short that it borders on under-specification, failing to provide any additional structured context. While it is not verbose, the lack of useful details reduces the value of its conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with four parameters and no output schema, the description is incomplete. It does not explain what 'trigger links' are, how search results are returned, or when this tool is preferred over alternatives. The annotations cover safety but not functional context, leaving significant gaps for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all four parameters (skip, limit, query, locationId) are already documented in the schema. The description adds no additional meaning or clarifications about how the parameters affect the search, such as the interpretation of 'query' in the context of trigger links. Since the schema handles parameter semantics, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Trigger Links' clearly states a verb (search) and a resource (trigger links). It distinguishes itself from sibling tools like links_get_links by specifying 'trigger links' as the search target, though it doesn't explicitly contrast with them. It's not a tautology and conveys the core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like links_get_links or links_get_link_by_id. The description does not mention any prerequisites, exclusions, or specific conditions for choosing this search over other link-related tools. Usage context is entirely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description 'Delete Custom Value' aligns with these but adds no further behavioral context such as permanence, side effects, or scope of deletion. With annotations present, the description contributes nothing beyond them, so the score is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—three words—with no redundant phrasing. The action is front-loaded and unambiguous. It earns a high score for brevity, though it lacks explanatory substance. It suffers from under-specification rather than verbosity, which is preferable but still limits its usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description is drastically insufficient. It fails to mention that the deletion is irreversible, what a custom value is in this domain, or any cascading effects. An agent cannot confidently invoke this tool without knowing the implications, especially given the presence of related create/update tools. The description provides no added context beyond the obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both id and locationId have meaningful descriptions). The description adds no parameter-specific info, but the baseline is 3 for high coverage. The locationId default behavior ('Defaults to GHL_LOCATION_ID when omitted') is already in the schema, so the tool description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (custom value), making the purpose unambiguous. However, it does not differentiate from sibling tools like locations_delete_custom_field or other delete operations, relying on the tool name for distinction. The verb-object structure is specific but lacks context on scope or uniqueness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of related operations like create or update. It simply restates the action without any conditional or contextual cues, leaving the agent to infer usage entirely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is non-read-only, idempotent, and non-destructive. The description adds no further behavioral context, such as whether it overwrites existing files, what happens to existing data, or any permission requirements. Given annotations already provide some safety cues, the description's lack of additional detail is a gap, but not a 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase, front-loaded with the key action. It is appropriately short for a simple tool, though it might be too terse to convey sufficient context. Structurally it is efficient with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool performs a bulk update on an array of file/folder objects, but the description gives no information about what fields can be updated, the format of the update objects, or expected outcomes. This is a significant gap for an agent needing to construct a request. The openWorldHint suggests additional unknowns, and the absence of an output schema makes it harder to understand what to expect. The description is far from complete for a tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all three parameters, so the description does not need to repeat them. However, the description does not clarify the structure of the 'filesToBeUpdated' array, which is the core parameter. With 100% schema coverage, the baseline is 3, but the description's lack of additional context about the array objects means it does not enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool updates files and folders in bulk. It clearly identifies the action (update) and the resource (files/folders), distinguishing it from singular updates through the 'Bulk' qualifier. However, it doesn't specify what properties can be updated or differentiate from other media tools beyond the bulk aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or conditions that would help an agent decide between this and the singular update tool. An agent must infer from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context—no mention of default locationId behavior, the effect of fetchProperties, or what the returned schema contains. With annotations covering basic traits, the description contributes nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise but also under-specified. It is front-loaded with the core action, yet the brevity borders on being too terse to be useful. It does not waste words, but it also fails to include any substantive detail that would justify its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given 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 should clarify the purpose and what the response looks like. It does not mention the `locationId` default or the `fetchProperties` effect, nor does it explain the return value structure. The schema provides parameter details, but the overall context is insufficient for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 3 parameters at 100%, and the description itself adds no extra meaning beyond what the schema provides. The phrase 'by key / id' is redundant and potentially confusing since there is no 'id' parameter. Baseline 3 is appropriate because the schema carries the explanatory load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and a resource ('Object Schema') and specifies the lookup mechanism ('by key / id'). It is unambiguous enough to understand the tool's basic function, but it does not differentiate from the sibling 'objects_get_object_by_location_id' or clarify that 'id' is not actually a parameter (only 'key' is).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'objects_get_object_by_location_id' or 'objects_get_record_by_id'. The description does not mention context, exclusions, or prerequisites, leaving the agent to infer the appropriate selection from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond the action itself—it does not mention return format, potential errors, or any operational nuances. With such strong annotations, some credit is given, but the description still contributes no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase—extremely concise. While it is efficient and front-loaded, it provides no enriching context. It is not verbose, but it also lacks any explanatory structure that might help an agent. It is appropriately sized for a simple getter but somewhat minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity get-by-ID tool, the description might be deemed sufficient, but it does not mention what is returned (since there is no output schema) or any side effects. The tool could return a subscription object, but without documentation, an agent is left to infer. Given the absence of an output schema, the description should at least hint at the return payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (altId, altType, subscriptionId) are already documented with their descriptions. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get Subscription by ID' which is a clear verb+resource pairing. It specifies the action (get) and the entity (subscription) with an identifier. However, it does not differentiate itself from sibling tools like payments_list_subscriptions or payments_get_order_by_id, though the name itself is reasonably specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of it being the single-subscription lookup versus listing subscriptions, nor any exclusions or caveats. An agent would have to infer from the name alone that this is for retrieving one subscription by ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=false and destructiveHint=false, indicating a safe, non-destructive write operation. The description adds no extra context about side effects, idempotency, or requirements beyond the verb 'create'. With annotations present, the description fails to provide additional behavioral value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, which is efficient. However, it under-specifies the tool's function, lacking any additional context that might be expected for a multi-parameter API. While not verbose, it is too minimal to be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, a nested seo object, and no output schema, the description does not explain return values, success criteria, or any constraints beyond required fields. It is incomplete for an agent to call this tool effectively without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, including explanations for name, slug, seo, and altId. The description itself does not add any parameter-related meaning, so it relies entirely on the schema. This meets the baseline of 3, but no enhancement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create Product Collection' clearly states a specific verb and resource, distinguishing it from other products tools like products_create_product. However, it does not elaborate on what a product collection is or its scope, leaving some ambiguity but enough clarity for a basic agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or sibling tools like products_update_product_collection or products_delete_product_collection. An agent must infer usage solely 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what annotations already provide (destructiveHint=true, idempotentHint=true). It does not mention side effects, irreversibility, or permissions, and without such context the agent cannot anticipate the consequences of deletion beyond the raw 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (three words) and concise, but it essentially restates the tool name. It lacks structure and does not 'earn its place' by adding meaningful detail beyond the name. It is not verbose, but it is under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description should provide at least some contextual information about the operation (e.g., irreversibility, scope, or prerequisites). It offers none, leaving the agent to infer behavior from annotations alone. This is insufficient for a deletion action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% – all parameters have descriptions in the schema. The description provides no additional parameter semantics, so it does not improve upon the structured documentation. Baseline of 3 is appropriate when the schema covers all parameters and the description adds nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Product Review' clearly states a specific action (Delete) and resource (Product Review), which is distinct from sibling tools like products_delete_product_by_id or products_delete_product_collection. It does not add extra context but is unambiguous and not misleading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description does not differentiate it from other delete tools or mention conditions under which it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description does not need to repeat safety information. However, it adds no additional behavioral context such as what is returned, error cases, pagination, or the relationship between productId and priceId. The description is a single clause with no extra disclosure, so it fails to add 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence. It is not overlong, but it lacks any structural elements like examples or clarifications. While brevity is positive, the description is so minimal that it provides no structure beyond a simple clause. It is not verbose, but it does not use conciseness to enhance usability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get-price tool with no output schema, the description should at least hint at the expected return or clarify the relationship between productId and priceId. The description is too sparse to be complete; an agent has no idea what the response will contain or if any permissions are needed beyond what annotations imply. Given the sibling tools include products_get_product_by_id and products_list_prices_for_product, failing to distinguish behavior leaves the tool under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for all three parameters (priceId, productId, locationId) with 100% coverage, so the description does not need to cover them. The description itself adds nothing about parameters, but the baseline of 3 is appropriate because the schema already handles semantics adequately. No additional parameter meaning is given in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Price by ID for a Product' clearly states the action (get) and the resource (price) with the scoping by product and ID. It is distinct enough from sibling tools like products_list_prices_for_product (which lists prices) and products_update/delete (which mutate), so an agent can infer the purpose. However, it is essentially a paraphrase of the tool name, adding no extra clarification beyond what the name conveys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this retrieves a single price by ID while products_list_prices_for_product lists all prices, nor does it state any conditions or exclusions. An agent must infer usage solely from the name and schema, which is insufficient for effective tool selection among many products_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not responsible for conveying safety. However, it adds no extra behavioral context such as return format, pagination, or any side effects. It does not contradict the annotations, but it does not enrich them either, so it meets the baseline for a safe read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler words. It is efficiently written and front-loaded, but extremely terse. It is appropriately concise for a simple read operation, though it lacks substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain what details are returned. The vague wording 'Details about individual product collection' leaves the agent uncertain about the response structure or the specific data fields. For a tool that is likely used to retrieve a collection, the description should at least outline the kind of information the caller will receive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for both parameters ('altId' and 'collectionId'), so the description does not need to add parameter details. It does not add any extra meaning beyond what the schema provides, so it earns the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb ('Get') and a resource ('product collection'), but the phrase 'individual product collection' is vague and does not clarify that this tool fetches a single collection by ID. It does not distinguish itself from sibling tools like 'products_get_product_collection' or 'products_get_product_by_id', making it hard for an agent to know which one is appropriate without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, filters, or why this tool exists alongside similar siblings. An agent must infer that it is for a specific collection ID, which is not stated in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, covering the safety profile. The description adds no additional behavioral context—it merely restates the tool's name in sentence form. It does not disclose what data is returned, whether results are aggregated, or any other operational details. With annotations carrying the risk information, the description should still add value by explaining behavior, but it does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence with no fluff, which is concise. However, it is so minimal that it borders on under-specification—it does not front-load any key details that would help an agent. While it is technically concise, it fails to earn its place by adding informative content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 5 parameters, no output schema, and annotations only cover safety, the description is expected to compensate by explaining what 'Product Store Stats' are and what the response contains. The description is silent on return format, what metrics are included, or any nuances of the query. This leaves an agent with insufficient context to confidently interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with each parameter having a description. Per calibration, this yields a baseline of 3. The description does not add any parameter-specific meaning beyond what the schema provides, so it neither improves nor detracts from the schema's clarity. The baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch') and a resource ('Product Store Stats'), which clearly identifies the tool's primary function. However, it does not elaborate on what 'stats' means or differentiate it from sibling tools like products_get_list_inventory or products_get_product_by_id. The purpose is clear but lacks the specificity needed to distinguish it from closely related product tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are no conditions, exclusions, or references to sibling tools. An agent would have to infer usage from the name alone, which is insufficient for making an informed selection among the many products_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which tells the agent this is a non-destructive, idempotent mutation. The description adds no behavioral details beyond the word 'update' – it does not mention partial vs. full update semantics, whether all fields are replaced, permission requirements, or any side effects. Since the description adds no value beyond the annotations, it scores low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is efficient and front-loaded. However, it is under-specifying: it omits any explanatory context that would be useful. Conciseness is not just brevity; it should be informative. Here the brevity leaves the description too bare, so it does not earn a 4 or 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 20 parameters, nested objects, and multiple conditional constraints. The description provides no information about update semantics (full vs. partial), required fields, or operational context. Even though the schema and annotations cover some details, the description is so minimal that an agent cannot fully understand the tool's behavior without inspecting the schema deeply. It should at least mention that this is a full update or note key dependencies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 95% schema description coverage, the schema already documents almost all parameters, so a baseline of 3 is appropriate. The description itself mentions no parameter details. While it could highlight conditional requirements (e.g., isLabelEnabled requiring label object), those are already in the schema descriptions. Thus, the description does not need to compensate, and it correctly stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Product by ID' clearly states the action (update) and resource (product) with an identifier. It is not a tautology and conveys the core function. However, it does not differentiate this tool from other product-related update tools like products_update_inventory or products_update_display_priority, which are siblings. Since it lacks sibling differentiation, it does not reach a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any context such as 'use for updating general product fields' or contrast with sibling tools like products_bulk_update or products_update_inventory. The agent receives no exclusions or conditions for selection. This is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive, idempotent mutation, so the description carries a lower burden. However, it adds no extra behavioral context beyond what annotations state—it doesn't explain whether updates are partial or full replacements, whether fields not specified are preserved, or any side effects. Without such detail, the description offers minimal value in predicting behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with no fluff—which is good for front-loading. However, it's so sparse that it offers almost no information beyond the name, so it's not earning its place as a useful description. It's appropriately sized in terms of brevity but fails to convey any actionable guidance, making it average in conciseness-structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with 7 parameters and no output schema, and it operates on an existing resource. The description provides no explanation of update semantics, required vs optional fields, or any constraints (e.g., whether slug changes are allowed). While annotations cover safety, they don't cover operational context. The description is incomplete for an agent to understand what fields can be changed and under what conditions, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all seven parameters are documented in the schema itself. The description adds no additional meaning about parameters—it doesn't highlight required vs optional fields, relationships, or usage hints. Since the schema fully explains parameters, a score of 3 (baseline) is appropriate; the description neither helps nor harms parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('Product Collection'), so an agent knows the basic function. However, it doesn't differentiate from siblings like products_create_product_collection or products_get_product_collection beyond the action verb, and it omits any mention of which fields can be updated. It's clear enough for a basic read of purpose, but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It doesn't mention that a collection ID is required (though schema makes it required), nor does it state any conditions like 'use when you have an existing collection ID' or contrast with creation/deletion. The description provides zero context for when this should be invoked, leaving the agent to infer based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the token scope constraint, which is useful contextual information beyond annotations, though it does not disclose return format, pagination, or other behavioral traits. This is a modest addition, consistent with a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the main action, followed by a key prerequisite. It contains no waste, though it may be too terse if more detail were warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter and no output schema, the description carries the burden of explaining the tool's scope. It provides a token requirement but does not explain what a custom snapshot is, what data it returns, or how it relates to sibling snapshot tools. This leaves the agent under-informed for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter companyId, which is described as 'Company Id'. The description does not add any extra meaning or context for the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Get' and resource 'Snapshots', but it does not mention 'custom' or clarify what distinguishes this from sibling snapshot tools like snapshots_get_latest_snapshot_push or snapshots_get_snapshot_push. It is not a tautology but is generic and lacks differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes a token requirement ('agency-level token, not a location PIT'), which is a prerequisite, but does not provide any guidance on when to use this tool versus alternatives. No mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. However, the description adds no behavioral context beyond repeating the verb. It does not disclose what data is returned, whether it returns a list or a single item, if there is pagination, or any authentication requirements. The description fails to leverage the annotations to enrich behavior understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is concise and free of fluff. However, it is so minimal that it borders on under-specification. It doesn't elaborate on expected behavior or context, but it is not verbose. The sentence does not earn its place because it adds little value; it is concise but not sufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters, but the description is incomplete. It does not state what the return value is, whether it returns a list of pages or a specific group, or any prerequisites like authentication. There is no output schema, so the description carries the burden of explaining the result. It fails to provide needed context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (accountId and locationId) are adequately described in the schema. The tool description adds nothing about parameters, so it provides no additional meaning beyond the schema. Since the schema already handles parameter semantics, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get facebook pages' clearly specifies a verb ('Get') and a resource ('facebook pages'). It is better than a tautology, but does not explicitly mention 'page group' as in the tool name, and it doesn't distinguish itself from the similarly-named sibling 'social_media_posting_get_instagram_page_group'. Still, it identifies the target platform and action clearly enough for an agent to understand the basic purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as sibling tools for Instagram, LinkedIn, or other platforms. It does not mention any conditions, exclusions, or context that would help an agent choose this tool over others. The agent is left without direction on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no additional behavioral context, such as what data is returned or any side effects. It provides zero 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of just one phrase. It is not verbose, but it is under-specified, providing minimal structure or front-loaded context. It is efficient but does not convey enough substance to be considered well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should at least hint at the return value or typical usage. It does not mention what 'google business locations' refers to or what the caller receives. Given the tool's simplicity, some mention of a list of locations would improve completeness, but it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (accountId and locationId) with descriptions, covering 100% of parameters. The description does not add any meaning beyond the schema, which is acceptable given the high schema coverage, but it also does not clarify how the parameters relate to the action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get google business locations' clearly indicates the action of retrieving Google Business locations for an account. It uses a specific verb and resource, and is distinguishable from siblings like get_account or get_posts. However, it does not elaborate on the scope or any filtering, so it is clear but lacks differentiation details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions. An agent has to infer from the name and schema alone, which is insufficient for a tool with related siblings like set_google_locations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the name—no mention of return structure, pagination, or platform caveats. It fails to add value beyond the 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence, but it essentially restates the tool name and carries no additional information. It is not front-loaded with critical context, and the brevity does not compensate for the lack of guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what statistics are returned (e.g., reach, impressions, engagement) and any access requirements. It does none of this, leaving the agent to infer the tool's behavior from the name and schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all parameters have detailed descriptions (e.g., platforms enum with platform-specific notes, locationId default, profileIds source). The description itself adds no parameter information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Social Media Statistics' uses a specific verb ('get') and resource ('social media statistics'), clearly distinguishing it from sibling tools that fetch accounts, posts, or profiles. It is not a tautology, but it lacks detail on what statistics are included, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, such as needing connected accounts, or any caveats like platform-specific limitations. The description gives no contextual selection cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal that this is a write operation (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description 'Create/Update' merely confirms mutation but adds no detail about whether it is an upsert, whether it replaces or merges settings, required permissions, or potential side effects. It fails to disclose any behavioral nuances beyond what the annotations state, so it adds little value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence, which is concise, but it is under-specified. It lacks critical context about which settings are affected and how they behave. While there is no verbosity or waste, the minimalism reduces its usefulness. It is appropriately short but not effectively informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with nested objects (shippingOrigin, two notification configurations) and no output schema, the one-line description is insufficient. It does not explain that it configures the store's shipping origin and order/fulfillment notification emails, nor does it mention defaults for altId/altType. An agent lacks the context needed to understand the tool's full purpose and requirements beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—every property like shippingOrigin, storeOrderNotification, and altId has a description. The tool description itself does not mention any parameters or add meaning to them. Per calibration, a baseline of 3 is appropriate when the schema fully documents parameters, and the description offers no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create/Update Store Settings' clearly indicates a mutation of store settings with a specific resource. It distinguishes itself from other store tools like carrier/shipping-zone managers, but does not explain what 'settings' specifically include (e.g., shipping origin, order notifications). It is not tautological and conveys a clear verb+resource, though it could be more explicit about the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or sibling tools (e.g., store_get_store_settings, store_update_shipping_carrier). An agent receives no context about appropriate scenarios or limitations, leaving usage entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds no behavioral context such as response format, pagination, filtering capabilities, or any side effects, which are absent from the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief with no fluff, which is concise, but it omits necessary details. It is under-specified rather than thoughtfully concise, so a middle score is appropriate given the trade-off between brevity and informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what is returned or any relevant behavioral aspects. It does not mention pagination, sorting, the structure of the list, or how altType affects results. This is a significant gap for a list operation, leaving the agent uncertain about the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents both parameters (altId and altType) with descriptions, achieving 100% coverage, so the description does not need to repeat them. However, the description also doesn't clarify how these optional parameters affect the list response, which would be useful for understanding their role beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'List' and the resource 'Shipping Carriers', making the core purpose clear. However, it does not differentiate from the sibling tool store_get_shipping_carriers, which could perform a similar function, so it lacks the specificity to distinguish among similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like store_get_shipping_carriers or store_list_shipping_rates. No context, exclusions, or comparisons are given, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context, such as pagination defaults, response format, or any side effects. It does not contradict the annotations, but it also provides zero value beyond the bare action, so it fails to add meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, which is not verbose. However, it is overly terse and fails to front-load any useful information beyond the action. It is minimally sized but at the cost of omitting critical usage and differentiation details. It earns a middle score because conciseness is appropriate, but structure lacks informative value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple nature and fully documented schema, the description should provide context on pagination, default location behavior, and when to use this list function versus alternatives like store_get_shipping_zones. It provides none of that. The absence of an output schema further increases the need for descriptive context, but the description is incomplete for an agent to correctly decide and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters (altId, limit, offset, altType, withShippingRate) having clear descriptions. The tool description does not mention or elaborate on any parameters, but the baseline is 3 when schema fully documents them. The description adds no extra semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and resource (Shipping Zones), providing a specific verb+resource combination. It is unambiguous about the core function. However, it does not differentiate from the sibling tool 'store_get_shipping_zones', which likely performs a similar retrieval. Thus it loses a point for lacking sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description simply states 'List Shipping Zones' without any context on selection criteria, such as whether to use this for paginated results or when the store_get_shipping_zones tool would be more appropriate. No exclusions or alternative conditions are provided, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write operation. The description adds nothing beyond the word 'Create,' which is implied by the tool name. It does not disclose side effects (e.g., whether the integration persists globally, requires OAuth, or affects other resources) despite openWorldHint=true. Since annotations cover the basic safety profile, a score of 3 is appropriate for minimal additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action, which is structurally clean. However, it is too terse to be genuinely useful on its own—it omits any context that would help an agent decide whether to call it. It is not verbose, but it sacrifices completeness for brevity, resulting in an average score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no additional context, the description is insufficient. It does not mention prerequisites (such as whether a Facebook page must already exist, whether OAuth is needed), nor does it explain the consequences of creating an integration or how this relates to the associated get_integration and delete_integration tools. An agent is left with only the name and schema, which is inadequate for a potentially complex setup operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions (pageId, locationId, adAccountId), so the schema already conveys their meaning. The tool description does not add any supplementary semantic detail or clarify relationships between parameters (e.g., whether adAccountId is required for page-level integration). With high schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Create') and resource ('Facebook integration'), which is unambiguous and distinct from the many other create_integration tools in the sibling list by including the platform. However, it is terse and does not elaborate on what 'integration' entails; the word 'Facebook' in the tool name does most of the disambiguation work, so the description itself is only marginally informative beyond that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as ad_manager_google_create_integration or ad_manager_li_create_integration. The description offers no context about prerequisites, typical use cases, or when to prefer it over the corresponding get_integration or delete_integration tools. An agent must infer applicability solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds no extra behavioral context such as reversibility, cascading effects on campaigns, or authentication requirements. It does not contradict the annotations, but it fails to provide any value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—three words—but it is under-specified. While it avoids waste, it does not structure information (e.g., what gets deleted or side effects). It is not verbose, but it fails to add value beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with no output schema, the description is incomplete. It does not mention consequences (e.g., permanent deletion, impact on associated campaigns), success/error behavior, or any prerequisites. The annotations cover safety, but an agent would benefit from knowing what happens when the account is deleted, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions). The description 'Delete ad account' adds no additional meaning to the parameters beyond what the schema already states (adAccountId as an identifier, locationId with a default). Since schema fully documents the parameters, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete ad account' clearly states the verb and resource. The tool name includes 'fb' to distinguish from Google and LinkedIn variants, though the description itself doesn't mention the platform. It's specific enough for an agent to infer its function, but it does not explicitly differentiate from sibling delete-ad-account tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or conditions that favor this tool over ad_manager_google_delete_ad_account or ad_manager_li_delete_ad_account. Without such context, an agent may struggle to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details beyond the basic 'Get' action, such as error handling, response format, or permission requirements. It is consistent with annotations but contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with zero wasted words. However, it is so terse that it essentially restates the tool name without adding substantive information, which is acceptable but not exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with annotations covering safety and schema covering parameters, the description is minimally adequate. However, there is no output schema or description of return values, error conditions, or edge cases, leaving some ambiguity for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for audienceId and locationId (including default). The description's mention of 'by ID' aligns with audienceId but provides no additional meaning beyond the schema. Baseline 3 applies due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: retrieving a custom audience by ID, which is a specific verb and resource. However, it does not differentiate from sibling tools like ad_manager_fb_get_custom_audiences (list) or ad_manager_google_get_audience_by_id, relying on the name for that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as listing all custom audiences or using Google's audience retrieval. There is no mention of prerequisites, typical scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context (e.g., return format, pagination, or side effects). Given the annotation coverage, a 3 is appropriate as it neither contradicts nor enriches 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.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single six-word sentence, which is technically terse but at the cost of essential context. It lacks any detail about the result set or parameter semantics, making it more under-specified than appropriately concise. The substance is insufficient for an agent to call it correctly without relying heavily on schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only 'get', the description is marginally sufficient given that the schema covers parameters and annotations cover safety. However, there is no output schema, and the description does not hint at the return structure (e.g., a list of Instagram account objects) or any special handling. It is complete enough for a trivial operation but lacks context that would aid an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the schema already explains pageId, type, and locationId. The description adds nothing extra about parameters. Baseline 3 applies since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('Instagram accounts for page'), making the primary purpose clear. However, it does not distinguish this from similar sibling tools like ad_manager_fb_get_pages or social_media_posting_get_instagram_page_group, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not specify any conditions, prerequisites (e.g., that pageId must be a Facebook page), or exclusions. An agent must infer usage solely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description's 'Create' adds no new behavioral information. It does not disclose side effects, required authentication, or what happens to existing settings. The description adds minimal value beyond the 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short ('Create Google integration') with no fluff, which is concise and front-loaded. It earns its place by stating the core action, though it omits important context. For its brevity, it is appropriately sized, but the lack of detail prevents a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, and the description does not explain what happens upon creation, what the integration is used for, or any prerequisites. Given the simplicity of parameters, a bit more context about the integration's purpose or return value would make it complete, but it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all three parameters with clear descriptions (e.g., mccId as 'MCC identifier', locationId with default behavior). The description itself adds no extra meaning beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and a resource ('Google integration'), which clearly indicates the action. It distinguishes from Facebook and LinkedIn integration tools by naming the platform explicitly. However, it does not elaborate on what an integration entails or what it does, so it is adequate but not richly informative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like ad_manager_fb_create_integration or ad_manager_li_create_integration. There is no mention of prerequisites (e.g., OAuth, existing MCC) or context that would help an agent decide to call this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'Delete ad account' and adds no behavioral context beyond what annotations already provide. Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, but the description does not elaborate on the irreversibility, consequences, or the permanence of the deletion. For a destructive operation, the agent would benefit from a warning about the impact, which is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence: 'Delete ad account' – extremely concise and front-loaded. There is no wasted wording. It is appropriately minimal for a clear action, though it lacks explanatory detail that could be added without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is inadequate for a destructive operation with no output schema. It fails to specify which ad platform (Google) explicitly, and it does not mention potential side effects, whether the deletion is permanent, or any required permissions or prerequisites. Given the existence of multiple platform-specific delete_ad_account tools, the missing platform context is a notable omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters (locationId and adAccountId) are fully documented in the schema with descriptions, so the description adds nothing extra. The schema coverage is 100%, so the baseline is 3. The description does not provide additional meaning or context for the parameters; it simply restates the tool's action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (ad account), making the core purpose unambiguous. However, it does not explicitly mention that this is specific to Google Ads, relying on the tool name 'ad_manager_google_delete_ad_account' for platform differentiation. With sibling tools for Facebook and LinkedIn also named 'delete_ad_account', the description alone does not disambiguate them, though it is still clear on what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the Facebook or LinkedIn delete_ad_account alternatives. No prerequisites, conditions, or context are given. An agent would have to infer from the tool name which platform it targets, and there is no advice on when deletion is appropriate or what to check beforehand. This is a significant gap given multiple similar siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context, such as what happens if the adAccountId does not exist, whether locationId is required in certain contexts, or any response format details. With no extra disclosure beyond the annotation, the description fails to enrich the agent's 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is an extremely concise single sentence, which avoids any bloat. It is appropriately brief for a simple get operation. However, it borders on under-specification because it omits any qualifying details, but given the tool's simplicity, this level of brevity is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two parameters, both documented in the schema, and no output schema, the description is minimally sufficient. However, it does not explain what 'details' include, whether there is any pagination, or how it differs from the plural 'get_ad_accounts.' For a getter with a single required identifier, this is a minimum-viable definition, but it leaves room for ambiguity about scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both adAccountId and locationId have descriptions in the schema. The tool description itself does not add any meaning beyond what the schema provides, such as the purpose of locationId or any constraints. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('ad account details'), which is specific enough for a simple getter. However, it does not distinguish itself from siblings like ad_manager_google_get_ad_accounts (which likely lists accounts) or ad_manager_li_get_ad_account_details (the LinkedIn variant). The singular/plural difference is implicit but not stated, so the agent must infer the differentiation from the name rather than the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it is a single-account lookup, nor does it contrast with listing tools or cross-platform variants. An agent must infer usage from the tool name alone, which is insufficient for routing to the correct sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds no behavioral context beyond what annotations provide—it does not mention return format, error conditions, or any side effects. Since the bar is lower with annotations, this scores low because the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero redundancy. It communicates the essential action immediately. While it is minimal, it is appropriately concise for a simple lookup tool, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 schema and annotations cover the required parameters and read-only behavior. However, the description does not indicate what the tool returns (e.g., audience details, fields, or response structure) since there is no output schema. The missing return information is a gap, but the core callability is covered. Overall, it is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both audienceId and locationId are described in the input schema. The tool description itself adds no parameter-specific meaning. Per the rubric, when schema description coverage is high, baseline is 3, and there is no additional value from the description, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get audience by ID' specifies a clear verb (Get) and resource (audience), and the 'by ID' distinguishes it from the plural sibling ad_manager_google_get_audiences. The name also reinforces the Google Ads context. It's specific enough for an agent to understand the primary function, though it omits details about what fields are returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like ad_manager_google_get_audiences (plural) or ad_manager_google_upsert_audience. The description does not mention prerequisites (e.g., having a valid audienceId) or contrast with list/upsert operations. An agent must infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully covers the safety and side-effect profile. The description adds absolutely no additional behavioral context—no mention of pagination, filtering, scope, return values, or any caveats. Since the description provides zero value beyond what annotations already convey, a score of 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single three-word sentence with no waste or superfluous detail. It is front-loaded and gets straight to the point. However, it is so terse that it borders on under-specification, so it does not earn a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the abundance of sibling tools with very similar names (get_conversions, get_conversion_by_id, get_audiences, etc.), the description lacks the context needed to disambiguate. It does not explain what 'conversion goals' means versus 'conversions', nor does it mention any specific behavior or limitations. The agent would be uncertain about which tool to call, making the description incomplete for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage and fully documents 'locationId' (including its default behavior of falling back to GHL_LOCATION_ID). The description adds no parameter information, so it does not enhance what the schema already provides. The baseline for full schema coverage is 3, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a verb ('Get') and a resource ('conversion goals'), making the basic purpose evident. However, it does not distinguish itself from sibling tools like ad_manager_google_get_conversions (which likely retrieves a list of conversions) or ad_manager_google_get_conversion_by_id (which retrieves a single conversion), so an agent cannot easily tell whether 'conversion goals' is a distinct concept or the same as 'conversions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many similar Google ad manager read tools. The description does not specify prerequisites, scoping, or comparisons to alternatives, leaving the agent to guess which tool is appropriate for a given intent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description doesn't need to state it's a mutation, but it also discloses no additional behavior—what 'publish' means (e.g., activating the ad, making it live), whether it's reversible, or side effects. The description adds no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Publish ad') with no waste, which is efficient. However, its brevity is borderline under-specification—it carries only the minimum information and doesn't front-load any contextual cues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple (one parameter, no output schema), the description offers no context about expected behavior, prerequisites, or return values. The agent gets no help in judging if this is the right tool for a given scenario, especially with so many sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (adId is described as 'Ad identifier'), so the schema already documents the parameter. The description adds no extra meaning, yielding a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Publish ad') on a specific resource, and the name includes 'google' and 'ad', distinguishing it from other platform tools. However, it doesn't explicitly contrast with sibling publishing tools like ad_manager_fb_publish_campaign or ad_manager_li_publish_campaign_group, limiting differentiation beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., ad must be in a draft state), and no exclusions. The description leaves the agent to infer usage from the name alone, which is insufficient given the many sibling ad-manager tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description offers no behavioral context beyond what the annotations already declare (readOnlyHint, idempotentHint, destructiveHint). It does not mention response format, authentication needs, or any caveats. Since annotations already cover safety, the description adds no value here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words, front-loading the core purpose. However, it is so brief that it omits any distinguishing or contextual information, making it only slightly above average in structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and numerous sibling tools, the description is insufficient. It does not indicate what specific ad account details are returned, nor does it help differentiate from other get_ad_account tools. For a simple getter, the description is too minimal to be considered complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (adAccountId and locationId), including the default for locationId, achieving 100% coverage. The description adds no additional semantic meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('ad account details'), and the tool name itself is explicit. However, it does not differentiate from sibling tools like ad_manager_li_get_ad_accounts (plural) or platform-specific get_ad_account_details tools, leaving potential ambiguity about which tool to choose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as ad_manager_li_get_ad_accounts or other platform-specific detail retrieval tools. There is no discussion of prerequisites, exclusions, or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond the verb, such as data aggregation, auth requirements, or response format. It does not contradict annotations, but it fails to disclose any additional behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase with no fluff, front-loading the verb and resource. While it is appropriately short, it is somewhat under-specified, but structurally it is efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain what reporting data is returned (e.g., metrics, dimensions) and how the fields parameter affects output. It also lacks any note on pagination or format. The description leaves the agent uncertain about the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter. The tool description itself adds no parameter-specific information. Baseline is 3 since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get campaign group reporting' clearly states a verb and resource, indicating it retrieves reporting data for a campaign group. It distinguishes from sibling tools like ad_manager_li_get_ad_analytics by specifying the entity (campaign group vs. ads), though it does not specify what kind of reporting metrics are included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like ad_manager_li_get_reporting_list or similar reporting tools for other platforms. The description does not mention any exclusions, prerequisites, or scenarios where this tool is preferred.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the sub-account/location scope but does not disclose pagination behavior or return format. Given the annotations, the description provides minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, a single sentence with no fluff. However, it may be too short to convey necessary usage details, but for conciseness it is excellent. Structure is simple and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has required pagination parameters (skip, limit) and an optional locationId, but the description does not explain what associations are, how pagination works, or what the response looks like. With no output schema and minimal description, an agent would lack key information to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%)—skip and limit have no descriptions. The description does not explain these parameters or their purpose. locationId is described in the schema, but the description adds nothing about how to use it. The description fails to compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation (Get) and resource (associations) with a scope (sub-account/location). It distinguishes itself from sibling tools like associations_get_association_by_id by indicating it retrieves all associations. However, it does not explicitly name the alternative or clarify what 'associations' refers to in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus other associations tools or any filtering conditions. It is a one-line statement without alternatives, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description merely repeats the action without adding context about permanence, side effects, or irreversibility. It offers no additional behavioral information beyond what the annotations provide, so it adds no value in this dimension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and contains no fluff. It efficiently communicates the core action, although it essentially restates the tool name. For a simple delete operation, this level of conciseness is appropriate and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward with two parameters, both documented in the schema. The description does not mention that deletion is permanent, but the annotation covers destructive behavior. It lacks guidance on when to use it, but given the simplicity, it is minimally adequate. No explicit mention of return values or side effects is present, but the output schema is absent, so the description could have added more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with clear descriptions (id and locationId). The tool description does not elaborate on them, but with 100% schema description coverage, the baseline is 3. The description adds no extra meaning beyond the schema, so it remains at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a Brand Board' states a specific verb and resource, clearly indicating the action. It does not explicitly differentiate from siblings, but the action 'delete' is sufficient to distinguish it from update/get operations. The purpose is unambiguous, though it adds no extra specificity beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as brand_boards_update_brand_board or brand_boards_get_brand_board_by_id. It does not mention any context, prerequisites, or scenarios where deletion is appropriate. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered by structured data. The description adds no additional behavioral context—it merely restates the action without discussing effects such as what happens if the calendar is already linked or whether schedule changes propagate. It does not contradict annotations but adds no value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant wording. It is front-loaded with the verb and resource. However, it is so terse that it misses the opportunity to clarify the exact semantic relationship, though for a simple tool this brevity is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with a complete schema and relevant annotations, the description is minimally sufficient. However, it does not explain the meaning of 'apply' in terms of how the schedule affects the calendar, nor any caveats about existing associations. The agent must infer the operation's semantics from the name and parameters, which is workable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented clearly ('id' as schedule identifier, 'calendarId' as team calendar identifier). The description does not add any further meaning about parameter relationships or constraints, so it stays at the baseline for high coverage without extra detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('apply') and the resources involved ('user availability schedule' and 'calendar'), which matches the tool name and distinguishes it from the sibling 'calendars_remove_calendar_from_schedule'. However, the direction of the relationship could be clearer: it says 'apply schedule to calendar' rather than explicitly 'add calendar to schedule', which might cause slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives like calendars_remove_calendar_from_schedule or calendars_update_schedule. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent to infer usage solely from the name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already declare (destructiveHint: true, idempotentHint: true). It does not mention permanence, side effects, or required permissions. With annotations present, the bar is lower, but the description still fails to add any extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a short verb-object phrase with no unnecessary words. However, it's so minimal it borders on being under-informative. It is well-structured and front-loaded, but could benefit from a bit more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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, the description plus annotations (destructive, idempotent) is minimally sufficient. But it lacks any explanation of return values or confirmatory behavior, and given the large sibling set, a bit more context would help an agent avoid misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter (calendarId has a description 'Calendar Id'), so the schema itself documents the parameter adequately. The description does not add any further meaning or format details, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Calendar' clearly states the verb and resource. It is distinct from sibling tools like calendars_delete_schedule and calendars_delete_calendar_resource, though it lacks explicit differentiation. The purpose is unambiguous but could be more specific about the calendar entity type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like calendars_delete_schedule or calendars_update_calendar. There is no mention of prerequisites, conditions, or exclusions, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, covering the mutation safety profile. The description adds no additional behavioral context, such as irreversibility, side effects on related appointments, or permission requirements. It's consistent with annotations but contributes nothing extra, so a 3 reflects adequate but not enhanced transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
At three words, the description is extremely concise and front-loaded with the action. However, this brevity borders on under-specification; it lacks any auxiliary detail that would help an agent, such as context about resource types or deletion consequences. It's not inefficient, but it offers minimal informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with two parameters, the description does not explain when to choose this over similar tools, nor does it mention potential impacts on schedules or the irreversible nature (though destructiveHint covers the latter). Without output schema, the agent gets no guidance on expected outcomes. The description is sparse relative to the information needed for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters: 'id' described as 'Calendar Resource ID' and 'resourceType' as 'Calendar Resource Type' with an enum. The description doesn't add new meaning beyond the schema, but since schema is complete, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Calendar Resource' clearly states a specific verb (delete) and resource (calendar resource), making the primary purpose unambiguous. While it doesn't explicitly distinguish from sibling tools like calendars_delete_calendar, the name itself carries the distinction, and the enum of resourceType (equipments/rooms) adds clarity. It's slightly above average because it conveys action and target precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as calendars_delete_calendar or calendars_update_calendar_resource. There is no mention of prerequisites, contexts, or exclusions. The agent must infer usage solely from the name and schema, which is insufficient for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows it is destructive. However, the description adds nothing beyond that—it does not disclose what happens to associated calendars, appointments, or whether deletion is reversible. With annotations covering the basic safety profile, the description should add context like cascading effects, which it fails to do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the action and object. It is front-loaded with the verb and the entity, and there is no wasted text. It is appropriately sized for a simple deletion operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (one parameter, simple deletion) and that annotations cover destructiveness, one might expect a slightly richer description. However, the description omits any detail about the consequences of deletion (e.g., whether it also removes calendars from the schedule) and lacks any caveats. It is minimal to the point of being under-specified for an operation likely to have side effects, so it is not complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single required parameter 'id' with a clear description: 'Unique identifier of the schedule to delete'. Schema description coverage is 100%, so the baseline is 3 even without extra info. The description does not add any details about the parameter (e.g., format, source), but it is not required given the schema completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'schedule' with a qualifier 'user availability', which distinguishes it from other delete tools like calendars_delete_calendar. It is unambiguous but does not elaborate on what constitutes a schedule or any additional scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, conditions, or exclusions. The description simply states the action without contextual cues such as 'Use when you need to permanently remove a schedule' or 'Do not use if you only want to remove a calendar from a schedule'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutation. The description adds no additional behavioral context—no mention of permanence, side effects, or permission requirements. Given the annotations, the description could have added value (e.g., 'permanently deletes the contact and removes all associated data') but does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two words—with no superfluous content. It is front-loaded and direct, which is appropriate for a simple delete operation. However, it borders on under-specification, but given the simplicity, the brevity earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter delete tool with annotations covering destructive behavior and no output schema, the description is minimally adequate. It lacks any elaboration on what happens after deletion (e.g., confirmation, cascading effects) or the context of the contactId (e.g., must be a valid contact). An agent could call it correctly, but more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's parameter description ('Contact Id') fully covers the meaning of contactId, and with 100% schema coverage, the description has no obligation to add parameter details. It provides no extra semantics beyond the schema, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Contact' clearly states the verb (delete) and resource (contact), making the tool's purpose unambiguous. It does not explicitly differentiate from sibling tools like 'delete_contact_from_workflow', but the intent is sufficiently clear for an agent to recognize this deletes a contact record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, such as when to use 'delete_contact_from_workflow' or other delete operations. There are no prerequisites, exclusions, or suggested conditions for invocation, leaving the agent without routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description 'Remove Contact From Every Campaign' adds no behavioral context beyond what the name and annotations convey. It does not mention irreversible side effects, the scope of campaigns affected, or any operational nuances. With annotations present, the bar is lower, but the description still fails to add value beyond the structural metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler words. It is appropriately concise for a tool with one parameter. However, it is so brief that it borders on under-specification, but it does not waste words, so it earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description is inadequate. It lacks context on the exact meaning of 'every campaign' (e.g., does it include archived campaigns? Is it reversible?), and provides no explanation of expected behavior or side effects. The one-parameter schema and absence of output schema mean the description must carry more explanatory weight, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'contactId', which is described as 'Contact Id'. The description does not add anything about the parameter beyond what the schema already provides. Given high coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Remove) and the resource (Contact) with a specific scope (From Every Campaign). It distinguishes this from the sibling 'remove_contact_from_campaign' by explicitly using 'Every', so the purpose is unambiguous. However, it is essentially a restatement of the tool name with minimal additional detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus the sibling 'contacts_remove_contact_from_campaign'. There is no mention of use cases, preconditions, or alternatives. The description alludes to bulk removal only through the word 'Every', but does not explicitly state when this should be chosen over single-campaign removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context, such as what the action object contains or whether the call has any side effects. Since annotations cover the safety, a neutral 3 is appropriate; no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence with zero wasted words. It is front-loaded and easy to parse. However, it is so terse that it borders on under-specification, though that is more a completeness issue than a conciseness flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two required parameters and no output schema, the description should explain what agentId is for, how to obtain actionId, or what the response will contain. It provides none of this. Even for a simple get-by-ID operation, the lack of context makes it difficult for an agent to call correctly without prior knowledge or external lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%: actionId has a vague description ('The unique identifier of the action ID Attached to the agent') that is redundant and unclear, while agentId has no description. The tool description does not compensate for this gap, failing to explain the meaning or relationship of the two required parameters. An agent would likely be confused about why agentId is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Action by ID' clearly states a verb (Get) and resource (Action) with a specific identifier. It is not a tautology and accurately reflects the tool's purpose. However, it does not differentiate from sibling tools like conversation_ai_list_actions or conversation_ai_get_agent, but the intent is clear without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any exclusions. The description provides no context about typical use cases, prerequisites, or scenarios where another tool might be more appropriate. The agent must infer usage solely from the name, which is insufficient for a large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a non-destructive write operation. The description adds no additional behavioral context such as side effects, permissions, or rate limits. It does not contradict 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two words), which is efficient but lacks any contextual structure. It does not front-load key information beyond the verb and object. While it avoids fluff, it is under-specified for a tool of this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 20 parameters and no output schema, the description is insufficiently complete. It does not explain what happens on success, error scenarios, or any behavioral nuances. The rich schema partially compensates, but more context is needed for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 20 parameters, so the baseline is 3. The description adds no parameter-specific meaning, but the schema fully documents each field. The description does not need to compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Update Agent'. However, it does not differentiate from sibling tools like conversation_ai_create_agent or conversation_ai_update_action. It is minimally descriptive but unambiguously indicates the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention conditions, prerequisites, or exclusions. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. Since annotations already declare destructiveHint=true and idempotentHint=true, the description does not disclose any additional side effects, auth requirements, or consequences. It simply restates the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a tool that has a near-identical sibling (conversations_cancel_scheduled_message). It does not clarify that this tool is specifically for email messages, nor does it provide any usage context, making it easy for an agent to select the wrong tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the emailMessageId parameter, so the schema documents it. The description does not add meaning beyond that, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: cancel a scheduled email message. It is specific about the resource (email message) and the verb (cancel). However, it does not explicitly differentiate from the sibling tool conversations_cancel_scheduled_message, which could be ambiguous for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or any conditions. The agent is left to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, signaling a mutating operation. The description simply restates 'Create', which is consistent but adds no extra behavioral detail such as side effects, permission requirements, or idempotency considerations. Given the annotations, the description is not misleading, but it does not enrich the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse—just three words—which is closer to under-specification than conciseness. It lacks any structure such as a sentence explaining the tool's purpose or context. A well-structured description would front-load the key action and then elaborate on important considerations, which this does not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 5 parameters and no output schema, the description is inadequate. It does not explain what a custom subtype is, why it is needed, or how the channel and language parameters affect the result. The agent must rely entirely on the schema and tool name, which may not be sufficient for correct usage in all contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all 5 parameters (100% coverage), including the enum for channel and defaults for locationId. The description adds no additional meaning beyond the schema, so it does not compensate for any gaps. The baseline of 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Create Custom Subtype'. It is specific enough to indicate the action and target, and the tool name reinforces the conversations context. However, it does not describe what a custom subtype is or how it relates to conversations, and it does not differentiate itself from siblings like conversations_update_custom_subtype or conversations_get_all_custom_subtypes. It is clear but lacks contextual nuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention that you should use this only for creating new subtypes, or that updates should go to conversations_update_custom_subtype. No context about prerequisites or typical use cases is provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond the annotations. Annotations already indicate the tool is destructive and idempotent, but the description does not elaborate on consequences (e.g., permanent deletion) or any other side effects. With annotations present, the description could still add value by explaining what gets destroyed, but it stays silent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two words, and is front-loaded with the action. It is not verbose or redundant, and every word serves a purpose. While minimal, it adequately conveys the operation for a simple delete tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema) and that annotations cover destructive and idempotent behavior, the description is minimally sufficient. However, it could be more complete by mentioning that deletion is permanent or irreversible, but it does not. Overall, it is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of the single parameter, including its type and description. The tool description adds no extra meaning to 'conversationId' beyond the schema. Per the rubric, a high schema coverage baseline of 3 applies, and the description does not exceed that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Delete' and the resource 'Conversation', clearly indicating the action. It is unambiguous and not a tautology, but it does not differentiate from sibling tools that also delete resources in the conversations domain, such as messages or scheduled messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are any exclusions or prerequisites mentioned. The description simply states the action without context for an agent to decide if this is the right tool for a given scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers safety. The description adds no behavioral context—no mention of pagination behavior (cursor), default channel filtering (implied in schema), or what happens when locationId is omitted (defaults to GHL_LOCATION_ID). The one-liner offers nothing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that is front-loaded with the core action and scope. No wasted words. Efficient and easily parsed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 optional parameters and no output schema, the description is severely under-specified. It doesn't explain what 'export' means (versus 'get'), how results are returned, whether there are any caveats, or how pagination works. The agent must rely entirely on the schema, which is unusual. A robust tool with this many filters should have more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description (e.g., channel filter behavior, cursor pagination). The description itself doesn't reference any parameters or add meaning beyond the schema. Baseline 3 is appropriate as the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Export') and resource ('messages') with a clear scope ('by location ID'). It's clear what the tool does, but it doesn't differentiate from sibling tools like conversations_get_messages or conversations_search_conversation, which also deal with messages. The name itself is descriptive, but the one-liner adds little beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It doesn't mention conditions, exclusions, or alternatives. An agent would not know if this is preferred over conversations_get_messages for specific use cases, or when to filter by channel or paginate. The description offers no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description does not mention pagination, ordering, or that it returns a list, despite the schema including limit and lastMessageId. This is a missed opportunity to enrich the agent's 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose. No fluff, no repetition. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema and with no explanation of return structure or pagination workflow, the description leaves gaps. The agent must infer that it returns a list of messages and how to page through them using the provided parameters. Sibling tools increase ambiguity, and there is no guidance to disambiguate. This is incomplete for a read operation that supports filtering and pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters including the default limit and the purpose of lastMessageId. The description adds no extra parameter semantics; baseline of 3 applies because the schema carries the load, and the description does not clarify nuances like how to combine limit and lastMessageId for pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and resource (messages) keyed by conversation id. It distinguishes from siblings like conversations_get_conversation and conversations_get_message by the plural 'messages' and the explicit 'by conversation id', though it does not explicitly contrast with the singular variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as conversations_get_message or conversations_search_conversation. It neither lists conditions for use nor mentions when not to use it, leaving selection to the agent's inference from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context—it doesn't describe return format, error behavior, or any side effects. With the bar lowered by annotations, a 2 is appropriate because the description still fails to add meaningful behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the core action, making it concise and easy to parse. While it is sparse, that's a matter of completeness rather than structure, so it earns a 4 for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should at least indicate what the transcription retrieval returns (e.g., text, URL, or an error). It doesn't, leaving the agent with no information about the expected response. For a simple tool, this is a significant gap that prevents the description from being complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the input schema already documents both messageId and locationId with clear descriptions, including the default behavior for locationId. The description does not add any parameter-specific semantics, so the baseline score of 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'transcription' keyed by Message ID, making the primary action unambiguous. However, it does not differentiate this tool from closely related siblings like conversations_get_message_recording or conversations_download_message_transcription, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. An agent must rely solely on the tool name and context to infer appropriate usage, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the fact that it returns a list, which is minor. It does not disclose pagination behavior or that the result is paginated, which would be useful, but given the annotations, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence that front-loads the primary action. It avoids unnecessary words and is easily readable. However, it is so brief that it borders on under-specification, hence a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters and only 20% schema coverage, the description is incomplete. It does not mention that funnelId is the identifier, that results are paginated via limit/offset, or any details about the returned list. Without an output schema, the agent lacks critical context to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only locationId has a description). The description provides no parameter explanations, leaving the purpose of funnelId, limit, offset, and name unexplained. With low coverage, the description should compensate, but it does not, so a score of 2 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch list of funnel pages' clearly states the action (fetch list) and resource (funnel pages). It distinguishes from related tools like 'funnels_get_funnels' (which gets funnels) and 'funnels_get_pages_count_by_funnel_id' (which gets a count). However, it is terse and could explicitly mention that it is filtered by funnel ID, though the name already implies this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, nor does it mention required parameters like funnelId or pagination (limit/offset). There is no explicit context for when an agent should choose this over other funnel-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), idempotentHint=false, and destructiveHint=false. The description adds no behavioral detail beyond the verb 'update'. It does not mention side effects, permissions, or what happens to the existing schedule, so it contributes little 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action efficiently. It is concise with no filler, though it lacks any additional structure or examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation tool with schema covering the parameter and annotations covering safety, the description is minimally sufficient. However, it omits any explanation of return values or side effects, and it gives no usage context among the many related invoice schedule tools, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'scheduleId', which is already described as 'Schedule Id'. The tool description adds no extra meaning to the parameter, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('scheduled recurring invoice'), making the core purpose clear. However, it does not distinguish itself from the sibling tool 'invoices_update_invoice_schedule', which also appears to update an invoice schedule, so it lacks explicit differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context is provided about prerequisites, the lifecycle of invoice schedules, or how this differs from related operations like 'invoices_schedule_invoice_schedule' or 'invoices_cancel_invoice_schedule'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what the tool name already implies. Annotations already indicate readOnlyHint=false (a write operation) and destructiveHint=false (non-destructive), but the description doesn't explain side effects like updating analytics, triggering notifications, or the idempotent nature (which annotation says is false). Since annotations are present, the description could add context about why this update matters, but it doesn't. It's essentially a verbal restatement of the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler or redundancy. It gets to the point immediately. It's concise, though it could arguably be more informative without being verbose. For a tool with one parameter, this level of brevity is acceptable, but it borders on being overly terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema), the description is still incomplete. It doesn't explain the purpose of updating 'last visited at' (e.g., for tracking user engagement) or any effects of calling it. An agent would have to guess why this specific field matters and what the response looks like. With no output schema, the description should provide more context about expected behavior, but it doesn't.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full description coverage (100%) for the single parameter 'invoiceId', so the description doesn't need to explain it. The schema's 'description' field already says 'Invoice Id', which is sufficient. The description itself adds no extra meaning about the parameter, so a baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update'), a specific resource ('invoice'), and a specific field ('last visited at'). It distinguishes this from general invoice updates by naming the exact field being changed, which helps an agent understand the narrow purpose. However, it doesn't explicitly differentiate from the sibling invoices_update_invoice_last_visited_at (which is identical) or other invoice update tools like invoices_update_invoice, so it's clear but not fully distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as invoices_update_invoice or the generic update tools. There is no mention of triggering conditions, prerequisites, or scenarios where this should be preferred. The description only says 'Update invoice last visited at' without explaining its typical use case (e.g., marking that a user has viewed an invoice), leaving the agent to infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description adds no behavioral context beyond restating the update action. It does not mention side effects, required permissions, rate limits, or 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no redundant words. It is appropriately concise for a simple update operation and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested objects (lateFeesConfiguration) and no output schema, yet the description provides no guidance on constructing the configuration, expected values, or response format. This is under-specified for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter meaning beyond what the schema already provides; all parameters are documented in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (template late fees configuration). It is specific enough to distinguish from other invoice update tools like payment methods configuration, though it does not explicitly contrast with siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as invoices_update_invoice_template or invoices_update_invoice_late_fees_configuration. It contains no context, exclusions, or mentions of sibling tools, leaving the agent to infer the appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, signaling a mutation, and the description merely echoes 'Create', adding no new behavioral context. There is no disclosure about side effects, failure modes, or idempotency implications beyond what annotations imply. The description adds no value over the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core action and scope with zero wasted words. It is highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with no output schema, the description omits practical context such as how to obtain the knowledgeBaseId, whether locationId is required or defaults, and what happens if the target knowledge base doesn't exist. While some of this is in the schema, the description should provide enough context for an agent to call the tool correctly without diving into the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear per-parameter descriptions (e.g., 'faq answer as a string', 'knowledge base ID as string'). The description itself doesn't add any extra meaning about parameters, so it relies on the schema. Per the rubric, a baseline of 3 is appropriate when schema covers everything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('a new FAQ') and adds the scope 'inside knowledge base', which distinguishes it from knowledge_base_create_knowledge_base. However, it doesn't elaborate on what 'FAQ' entails (question/answer pair), so a slight ambiguity remains about the exact resource being created.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like knowledge_base_create_knowledge_base or knowledge_base_update. It doesn't mention prerequisites (e.g., needing an existing knowledgeBaseId) or any context that would help an agent decide to invoke it over similar create operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose that this initiates an asynchronous process, that it may take time, or that it changes state (since readOnlyHint=false). It does not mention what happens to discovered URLs or whether the agent should poll for status. The only hint is 'start crawling' which implies a long-running operation, but it lacks any detail on expected behavior or 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core action. It is front-loaded and avoids unnecessary detail. While it is very brief, it is not padded with fluff, and the structure is acceptable for a simple action verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool lacks an output schema, so the description must explain what the tool returns or what to expect after invocation. It does not mention that the crawl is asynchronous, that status can be checked via knowledge_base_get_crawling_status_for_latest_operation, or what the 'option' parameter (Exact, Path, Domain) means. The description is incomplete for a tool that initiates an async process and has no other explanatory context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all parameters with descriptions (URL as string, option as enum, locationId with default, knowledgeBaseId as string). The description adds no additional meaning beyond the schema; it only repeats 'training' which is already implied by the knowledge base context. With 100% schema coverage, the description provides no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Start crawling and discover pages for training' clearly indicates an action to initiate a crawl for a knowledge base's training. It distinguishes from sibling tools like knowledge_base_train_discovered_urls (which trains after discovery) and knowledge_base_get_crawling_status_for_latest_operation (which checks status). However, it does not explicitly mention the knowledge base context, though the name and required knowledgeBaseId parameter make it clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus related tools such as knowledge_base_train_discovered_urls or knowledge_base_get_crawling_status_for_latest_operation. It does not mention that this is the first step in a crawl-train workflow, nor does it state prerequisites like creating a knowledge base first. No differentiation or workflow context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive, non-idempotent operation, and the description adds no further behavioral context. It does not disclose whether the operation is asynchronous, whether it returns a status, or how it relates to the `operationId` parameter. With annotations present, the bar is lower, but the description still fails to convey any valuable behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no redundant words. It conveys the core action efficiently and is front-loaded with the primary verb. However, it is too sparse to cover important context, so it earns a 4 for brevity but not a 5 because the conciseness sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is drastically underspecified for a tool with four parameters and no output schema. It does not explain the relationship between urlIds and operationId, mention that operationId likely comes from a discovery operation, indicate any asynchronous behavior, or state what the tool returns. An agent would struggle to use it correctly without diving into the schema or external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning every parameter (urlIds, locationId, operationId, knowledgeBaseId) already has a description in the input schema. The tool description adds no extra parameter-specific information, so it relies entirely on the schema. This matches the baseline of 3 when schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('train') and the resource ('discovered website pages') and destination ('knowledge base'), which distinguishes it from discovery or deletion tools. However, it does not explicitly differentiate from the sibling `knowledge_base_discover_website` beyond the verb, and it lacks an explicit alternative name, so it is clear but not maximally distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no direct guidance on when to use this tool versus alternatives. The phrase 'discovered website pages' implies it should be used after discovery, but it does not state the prerequisite (e.g., 'use after knowledge_base_discover_website') or any exclusions. An agent would have to infer the context from the name and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Update', which aligns with readOnlyHint=false and destructiveHint=false from annotations. It does not disclose any additional behavioral traits such as side effects on related data, permissions (e.g., requiring write access to the knowledge base), or idempotency implications. With annotations covering the safety profile, the description adds no value beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise, but it omits any helpful details such as what fields are updateable or that all three parameters are required. It is not verbose, but the brevity comes at the cost of useful context. It is appropriately sized for a trivial operation, yet lacks explanatory depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: update an existing FAQ with id, question, and answer. The schema documents all parameters, and the annotations cover the safety profile. The description adds the fact that the FAQ must 'exist', which is useful, but it does not mention that the ID must correspond to a valid FAQ entry or any other practical caveats. For a simple update, this is minimally adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all three parameters (id, question, answer) clearly described as strings. The tool description does not add any additional meaning about parameter relationships, formats, or constraints beyond what the schema already provides. No extra semantic value is contributed, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and a specific resource ('an existing knowledge base FAQ'), which distinguishes it from sibling tools like knowledge_base_update_knowledge_base. It is not as rich as mentioning what fields are updatable, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., knowledge_base_create or knowledge_base_delete). There is no mention of prerequisites, such as needing an existing FAQ ID, or scenarios where this should be preferred. Usage context is entirely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=false, indicating a non-destructive write. The description simply says 'create', which aligns with the annotations but adds no additional behavioral context, such as what side effects occur (e.g., charging a wallet, applying funds) or whether the operation is reversible. Essential transparency for a mutation tool is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no fluff. It's appropriately short for a simple action, though given the tool has 10 parameters, a bit more context could be beneficial without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 10 parameters, no output schema, and a minimal description. It doesn't explain the domain context (what constitutes a wallet charge), how parameters relate to each other, what the response format is, or any prerequisites. For an operation with this complexity, the description is insufficient for an agent to use it confidently without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for all 10 parameters. The description does not add any parameter-specific meaning beyond the schema, which is adequate given the schema's completeness. The baseline of 3 applies since the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('new wallet charge'), which clearly distinguishes it from sibling tools like marketplace_delete_charge and marketplace_get_charges. However, it's terse and doesn't elaborate on what a 'wallet charge' means in this marketplace context, leaving some ambiguity for agents unfamiliar with the domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs. alternatives. It doesn't mention that this is the create counterpart to marketplace_get_charges or how to handle prerequisites. An agent is left to infer the appropriate usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not contradict annotations, but it adds no behavioral context beyond what annotations already provide. Annotations already flag destructiveHint: true and readOnlyHint: false, so the agent knows it is destructive. The description merely repeats the verb 'Uninstall' without disclosing side effects (e.g., removal of associated data, scope of uninstallation) or any additional behavioral details. It adds nothing beyond the annotation profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded and free of extra words. It earns its place by stating the core action. However, it is so brief that it borders on under-specification, but for a dimension focused on conciseness and structure, it scores well for not wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a destructive nature, conditional parameter requirements (reason required for developers, companyId required for agency tokens, locationId defaults to GHL_LOCATION_ID), and no output schema. The description is far too minimal to convey these nuances. An agent calling this tool without consulting the schema could easily misuse it, e.g., omitting reason when uninstalling as a developer or failing to specify scope. The description should at least hint at these conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (appId, reason, companyId, locationId) are documented in the schema. The description itself adds no parameter semantics—it does not mention any parameter details. Since the schema carries the full burden, the baseline of 3 is appropriate; the description neither helps nor hinders.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Uninstall an application' clearly states the action (uninstall) and the resource (application), making the tool's purpose unambiguous. However, it does not differentiate from sibling marketplace tools like marketplace_get_charges or marketplace_delete_charge, though those are obviously different operations. It lacks any contextual specificity about scope (agency vs location), so it is clear at a basic level but not fully distinct from similar uninstall-like operations in the same domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no conditions, no prerequisites, and no mention of the nuances covered in the parameter descriptions (e.g., reason required for developers, companyId for agency tokens). An agent must infer usage solely from the schema, which is insufficient for a destructive operation with conditional requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already disclose the tool's safety profile, so the bar is lower. However, the description adds zero behavioral context beyond a generic 'Get Opportunity'. It does not describe return format, potential errors, or any special behavior, contributing nothing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase with no redundancy. It efficiently communicates the core purpose without waste. While it could be slightly more descriptive, it is appropriately minimal for such a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description is minimally adequate. However, it omits usage context such as when to use this tool over search tools and does not hint at the return value. It is complete enough to call but lacks guidance for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the 'id' parameter, including a description ('Opportunity Id'). The tool description adds no additional meaning about the parameter (e.g., format, requirements, or default behavior). With high schema coverage, the baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource pair ('Get Opportunity') and implies retrieval of a specific record via the 'id' parameter. It is distinguishable from sibling tools like opportunities_search_opportunity and opportunities_get_pipelines, but does not explicitly state 'by ID' in the description, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as opportunities_search_opportunity or opportunities_get_pipelines. The description does not mention conditions like 'use when you have the opportunity ID' or when to prefer search tools. This is a significant gap for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds no behavioral detail beyond the literal action—it doesn't mention pagination, default limits, ordering, or response format, which are not covered by 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two words with no fluff. It is front-loaded and to the point, though arguably too sparse to convey the tool's full capability, it does not waste any words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters and no output schema, the description is incomplete. It does not explain what the response contains, pagination behavior, or any default settings. An agent relying on this description alone would not know whether the tool returns all coupons or requires filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all six parameters, so the baseline is 3. The description 'List Coupons' adds no extra meaning or context about how parameters interact (e.g., how limit/offset control pagination).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Coupons' uses a specific verb (List) and resource (Coupons), clearly indicating a read operation that returns multiple coupons. It differentiates from siblings like payments_get_coupon (singular) and payments_create_coupon, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as payments_get_coupon for retrieving a single coupon, or when to apply filters like status or search. The context is implicit from the tool name but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description 'Record Order Payment' essentially repeats the tool name and adds no behavioral detail beyond what annotations already convey (readOnlyHint=false, destructiveHint=false). It does not clarify side effects like updating order status, creating a transaction entry, or whether it is idempotent. The annotations provide safety info, but the description contributes nothing extra, so it fails to inform the agent about what actually happens.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single phrase with no unnecessary words. It is front-loaded and to the point, which is good for agent readability. However, it lacks any structural elements like examples or conditional clarifications, but given its simplicity, the conciseness is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 10 parameters, including nested objects (card, cheque) and enums, yet the description provides no contextual guidance on how to compose these parameters or what the tool returns. With no output schema defined, the agent is left to infer the result. The description fails to cover essential details like which parameters are required, how partial payments are handled, or what a successful call returns, making it insufficiently complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 10 parameters, so each parameter is already documented with types and enums (e.g., mode enum with cash/card/cheque/bank_transfer/other). The description 'Record Order Payment' adds no additional meaning to parameters. With full schema coverage, a baseline of 3 is appropriate as the description does not hinder but also does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Record Order Payment' clearly states a specific verb ('Record') and resource ('Order Payment') that matches the tool name. It is unambiguous about the action, but it does not differentiate from sibling tools like payments_create_order_fulfillment or payments_list_orders, though those are distinct operations. The phrase is sufficient for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any preconditions, when not to use it, or how it fits into the payment workflow. An agent has no context about whether this is the right tool for a given scenario, such as partial payments or invoice payments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds no behavioral context beyond the name—no mention of pagination defaults, filtering behavior, return format, or any side effects. It neither contradicts nor enriches the annotations, so it contributes little to behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that directly states the purpose. It is extremely concise and front-loaded with the core operation, with zero wasted words. This is an excellent example of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description is minimal. It doesn't explain what 'active numbers' means in the phone system context, nor does it describe how this relates to other phone system tools or what an agent should expect from the response. The description is inadequate for an agent to correctly invoke this tool across varied use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with all 5 parameters (page, pageSize, locationId, searchFilter, skipNumberPool) documented in the input schema. The description itself does not add any parameter-level meaning, but since the schema carries the full burden, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List active numbers' clearly identifies the verb (List) and the resource (active numbers). It is specific enough to convey the operation, but it does not differentiate from sibling tools like phone_system_available_numbers, which could be confused with active numbers since both may return phone numbers. The lack of scope or distinction prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as phone_system_available_numbers or phone_system_purchase_phone_number. No mention of typical scenarios, exclusions, or prerequisites. The agent is left to infer usage from the name and schema, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the basic action. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. However, the description does not mention any additional behaviors like pagination, limits, or that it returns a list, which are not implied by 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is appropriately front-loaded with the core action. It could be slightly more descriptive, but it is efficient for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, a required countryCode, and no output schema, the description is too minimal. It does not explain the business context (e.g., searching for purchasable numbers), any response format, or why filters like MMS/SMS/voice matter. The user cannot fully understand the tool's purpose from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 9 parameters are already documented in the input schema. The description adds no additional meaning about the parameters or their usage, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List available phone numbers' clearly states the verb (list) and resource (available phone numbers). It is specific enough to distinguish from other phone system tools by indicating the 'available' state, though it does not explicitly contrast with siblings like phone_system_active_numbers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as phone_system_active_numbers or phone_system_get_number_pool_list. There is no mention of prerequisites like needing a location ID or why one would search for available numbers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a write operation (readOnlyHint false) and non-destructive (destructiveHint false), but the description adds no behavioral context. It does not explain whether the edit replaces entire product objects or merges properties, nor does it disclose any limits on batch size or the nature of price updates. The only extra detail (total count includes all prices) comes from the parameter schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant wording. It front-loads the action and target, making it easy to scan. However, it might be too terse, but the dimension measures conciseness and structure, not completeness, so a short, clear statement earns a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk edit operation that can modify multiple products and prices, the description is inadequate. It does not specify which fields can be edited, whether prices are updated as a whole, or how errors are handled. The lack of an output schema and minimal description leaves an agent uncertain about the operation's scope and consequences.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The tool description itself adds no additional meaning beyond what the schema provides. The 'products' parameter description in the schema already includes the important note about total count including prices, so the description does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Bulk Edit Products and Prices' states a clear verb (edit) and resource (products and prices), which is not a tautology. However, it does not differentiate from the sibling tool 'products_bulk_update', which likely performs a similar function, so it lacks the specificity needed to distinguish between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over alternatives, such as 'products_bulk_update' or individual product update tools. There is no mention of constraints, prerequisites, or conditions that would help an agent decide between this and similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. However, the description adds no additional behavioral context. It does not explain pagination (limit/offset), the shape of the returned data (there is no output schema), or what happens when no filters are provided. Since the description carries little value beyond the annotations, and there is no output schema to clarify returns, a score of 2 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence, 'Fetch Product Collections', which is clean and to the point. It is front-loaded with the core purpose and contains no fluff. However, it is perhaps too terse—it omits important functional details that could be added in a second sentence without becoming verbose. Still, as written, it demonstrates good structure and no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters including pagination and search filters, and no output schema, the description is not complete enough for an agent to call the tool correctly. The agent lacks information about the return structure, how pagination works, or that filtering by name/collectionIds is possible. The annotations cover safety but not functional completeness. A more informative description explaining search and pagination behavior is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters have descriptions in the schema itself. The description 'Fetch Product Collections' does not add any extra meaning to the parameters (e.g., clarifying that `name` is a partial match or that `collectionIds` is comma-separated). Since the schema already documents each parameter, the baseline of 3 applies; the description neither enhances nor detracts from parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch Product Collections' clearly states the action (fetch) and resource (product collections). It is a straightforward verb+resource statement that indicates a read operation. However, it does not differentiate from siblings like products_get_product_collection_id, but the plural form implies it returns multiple collections, which distinguishes it. Overall, it is clear and not misleading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for listing or searching collections, nor does it contrast with products_get_product_collection_id (which fetches a single collection by ID) or the create/update/delete variants. The schema parameters (name, collectionIds) imply search capability, but the description does not surface this. An agent must infer usage from the schema alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly=false, destructive=false), but the description adds nothing beyond the word 'update'. It does not disclose whether updates are partial or full replacement, how priorities are applied, or any side effects on existing data. For a mutation tool, this is a significant gap in behavior disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no fluff. It front-loads the action and resource, making it easy to parse. There is zero waste; it is appropriately concise for its limited scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a relatively complex schema (4 parameters, one being a nested array), the description is too terse. It does not explain the structure of the products array, the meaning of 'display priority', or any return values (no output schema). Given the complexity and missing output schema, this is inadequate for an agent to correctly invoke the tool without more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes all parameters with 100% coverage, including 'products' as 'Array of products with their display priorities'. The description adds minimal value beyond confirming the domain. It does not clarify the inner structure of the products array (which schema leaves as array of arrays with empty items), so it fails to compensate for the schema's ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (product display priorities) within a store context. It is specific enough to distinguish it from generic product updates, though it does not explicitly differentiate from sibling tools like products_bulk_update or products_update_product_by_id. The mention of 'display priorities' provides a distinct purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternative product update tools, nor does it mention any preconditions, such as whether a store must exist or how priorities relate to other updates. There is no exclusion or alternative mentioned, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the description does not need to repeat that it is a read operation. However, it adds no additional behavioral context such as authentication requirements, rate limits, or what exactly is returned (e.g., whether both page and profile data are included). The description is consistent with annotations but fails to enrich the agent's understanding beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, 'Get Linkedin pages and profile', which is efficient and front-loaded. It is concise without being overly verbose. However, it is somewhat sparse, so while it earns its place, it could slightly elaborate without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read tool with two parameters, but there is no output schema and the description does not explain what the response will contain or what exactly is fetched. An agent cannot know if it returns both page and profile details, or if additional fields like account name or profile URL are included. Given the lack of output schema, the description should compensate, but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both accountId and locationId are described in the schema. The description adds no extra parameter meaning, but according to the rubric, when schema coverage is high the baseline is 3. The description does not compensate for any undocumented aspects, but since all parameters are documented, a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb 'Get' and resource 'Linkedin pages and profile', which is distinct from sibling tools like get_facebook_page_group or attach_linkedin_page_profile. It is unambiguous that this retrieves LinkedIn-related data, though the exact scope (pages vs profile vs both) is slightly vague, so it does not fully disambiguate from other LinkedIn getters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or scenarios where this should be preferred over other social media get tools. An agent cannot infer when this is the right choice without additional context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond these annotations—it does not disclose pagination behavior, default parameter values (already in schema), or output format. Since the description provides zero additional disclosure, it falls short of the baseline for annotated tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy. It is extremely concise and front-loaded, conveying the core action immediately. Every word earns its place, so a top score for conciseness is warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema and all optional parameters, the description is too brief to be complete. It omits any mention of return structure, pagination implications, or how this differs from social_media_posting_get_tags_by_ids. An agent would have to rely on the schema alone to understand the tool's full behavior, making the description contextually insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (skip, limit, locationId, searchText) are documented in the schema. The description itself adds no parameter-specific meaning—it only mentions 'location id' which is already covered by the schema's 'Location Id Defaults to GHL_LOCATION_ID'. Given the high coverage, a baseline of 3 is appropriate; the description neither enriches nor detracts from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get tags by location id' clearly states the action (get), the resource (tags), and the key filter (location id). It is specific enough to convey the tool's purpose, though it does not explicitly differentiate from siblings like social_media_posting_get_tags_by_ids, which retrieves tags by IDs. The verb+resource pattern is solid, so a 4 is appropriate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention the sibling tool social_media_posting_get_tags_by_ids or any conditions that would select one over the other. There is no context about typical use cases, filtering, or pagination. The absence of any usage direction leaves the agent to infer, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which covers safety. The description adds no behavioral context beyond that—no mention of auth requirements, response format, or what happens if the account isn't a business account. It is consistent with the annotations but contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is efficient and front-loaded, but it is also essentially a restatement of the tool name without added nuance. It earns its place, but just barely; there is no elaboration to structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get tool, the description omits critical context: what information the profile contains, whether a business account must be connected, or how the result should be used. While the annotations cover safety, the lack of usage context and the existence of a sibling tool make this incomplete for an agent to reliably select and execute it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a brief but functional description. The tool description adds no parameter-level detail, so the baseline of 3 applies. The schema's 'Defaults to GHL_LOCATION_ID when omitted' is helpful, but it comes from the schema, not the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'Tiktok Business profile'. However, it fails to distinguish this tool from the nearly identical sibling social_media_posting_get_tiktok_profile, so an agent might not know which profile variant to use without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus the non-business TikTok profile getter, nor does it mention any prerequisites like having a connected business account. No alternatives are named or excluded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no extra behavioral detail such as what data is returned, any authentication requirements, or what happens if the profile doesn't exist. It essentially restates the tool's name without enriching the agent's understanding 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise single sentence with no wasted words. It is appropriately sized for a simple read operation and front-loads the core action and resource. While it could include more detail, it does not suffer from verbosity or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description should clarify what the returned profile data contains and differentiate it from the sibling business profile tool. It fails to explain the purpose of accountId and locationId beyond the schema, and does not mention any prerequisites or typical use cases. The lack of context makes it incomplete for agents choosing between related profile-fetching tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters (accountId and locationId), so the schema already explains their meanings. The description adds no additional context about parameter usage, defaults, or how they relate to the profile retrieval. Baseline of 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and resource (TikTok profile), making it unambiguous what the tool does. It distinguishes from other social media tools by specifying TikTok, but it does not explicitly differentiate from its sibling 'social_media_posting_get_tiktok_business_profile', which is a closely related tool that could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as the TikTok business profile variant or attach/oauth tools. It does not mention prerequisites like having an existing accountId or any setup steps. The description provides no context for selecting this tool over others in the same family.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds no behavioral context beyond the verb 'Starts', such as whether the OAuth flow returns a redirect URL, requires a callback, or has side effects. It does not contradict annotations, but it also does not enrich them, leaving the agent without expectations for the flow.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It is front-loaded with the essential action and resource, making it easy to parse. In terms of conciseness, it is exemplary; the issue is under-specification, not verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that initiates an OAuth flow, the description is incomplete. It does not indicate that the tool may return a URL for user authorization, that it requires a redirect URI, or that the flow typically involves subsequent steps. Even with annotations covering safety and schema covering parameters, the lack of behavioral context leaves an agent unsure of the invocation's outcome or next steps, especially given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented with basic descriptions (page, userId, reconnect, locationId). The description itself adds no additional meaning to the parameters, which is acceptable given the high schema coverage. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Starts OAuth For Facebook Account' clearly states the verb (Starts) and resource (Facebook Account) and distinguishes it from sibling OAuth starters (e.g., Google, Instagram). However, it is terse and could benefit from mentioning the specific platform and that it initiates an authorization flow, but it is unambiguous in identifying the tool's core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling 'social_media_posting_start_*_oauth' tools. It does not explain prerequisites, the need for user interaction, or conditions that would make this specific tool the right choice. The context (Facebook-specific) is implied but not explicitly stated as a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover safety expectations. However, the description adds no additional behavioral context, such as what 'starting OAuth' entails (e.g., returns a URL, requires user interaction, or changes state). The description does not contradict annotations, but it also fails to elaborate on the behavior beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the core verb and resource. It is concise with no fluff. However, it is so brief that it sacrifices important details like expected output or flow, but from a conciseness perspective it is well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is an OAuth initiation tool with no output schema, the description is severely lacking in context. It does not explain what the agent should expect in response (e.g., a URL, success/failure indicator, or redirect), nor does it describe the OAuth flow steps. This is a significant gap for a tool that likely initiates a multi-step authentication process. The description fails to compensate for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (page, userId, reconnect, locationId) have schema-level descriptions. The tool description itself does not add any extra meaning to these parameters. Since the schema carries the full semantic weight, the baseline of 3 is appropriate—no added value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Starts OAuth For Instagram Account' clearly indicates a specific action (starting OAuth) on a specific resource (Instagram account). It distinguishes itself from sibling OAuth starts for Facebook, Google, LinkedIn, etc., by naming Instagram. It is not a tautology and adds clarity about the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for Instagram specifically or that other similar OAuth tools exist. No context is given about prerequisites, fallback options, or when not to use it. The agent must infer usage from the tool name and siblings, which is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat those. However, it adds no behavioral context beyond 'starts OAuth' — it doesn't mention the flow's outcome, whether a URL is returned, or any external side effects. The description carries little additional 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no fluff. It gets to the point, but it is so brief that it borders on under-specification. Still, it is efficiently written for the purpose it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters and no output schema, the description leaves out critical details: what each optional parameter (Page, Reconnect) means, what the expected response is (e.g., a URL), and how to complete the OAuth flow. The context of many sibling tools also demands more differentiation. The description is insufficient for an agent to confidently invoke without additional research.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters (Page, User Id, Reconnect, Location Id), so the baseline is 3. The description adds no further parameter meaning, and the schema descriptions themselves are minimal ('Page', 'Reconnect' are ambiguous), but the description does not help clarify them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Starts OAuth For LinkedIn Account' clearly states a specific action (starts OAuth) on a specific resource (LinkedIn account). It distinguishes from other platform OAuth tools by naming LinkedIn. However, it does not distinguish from related LinkedIn tools like attaching a profile, relying on the name for that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many sibling OAuth start tools (Facebook, Google, etc.) or the attach_linkedin resource. It does not indicate prerequisites, whether a user must be authorized, or if reconnect should be used. The agent is left to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true, so the description's 'Delete' is consistent. However, the description adds no additional behavioral context (e.g., permanence, cascading effects, or that the operation cannot be undone). Since annotations cover the primary destructive nature, the description meets minimum expectations but provides no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, which is front-loaded but arguably under-specified. It is not verbose, but it lacks sufficient substance to be considered well-structured for the purpose of guiding an agent. The brevity might be appropriate for a well-known pattern, but here it leaves gaps that other dimensions already penalize.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description is too sparse. It does not mention that the deletion is permanent, whether it affects associated shipping rates or zones, or any other consequences. Annotations provide destructiveHint, but the description adds nothing to the overall context, leaving an agent to wonder about side effects. Given the simplicity of the tool, it could still be improved with one or two sentences of context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for all three parameters (100% coverage), so the baseline is 3. The tool description adds no parameter-level detail, and there is a notable issue: the schema for shippingCarrierId says 'ID of the shipping carrier that needs to be returned' which is misleading for a delete operation, but this is a schema defect, not a description issue. The description itself does not clarify or augment parameter meanings, so the score remains at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('shipping carrier'), which clearly identifies the primary action and target. It is distinct from sibling delete tools like 'store_delete_shipping_rate' by naming the carrier explicitly, though it does not elaborate on the scope or context. The name and description together make 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusion conditions. An agent would have to infer context from the name alone, with no direction on when to choose this over similar delete operations like store_delete_shipping_rate or store_delete_shipping_zone.
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 is consistent with the annotations (destructiveHint: true), but it does not add any behavioral context beyond what the annotations already declare. Since the annotations indicate destructive behavior, the description does not need to repeat it, but it also fails to disclose any additional traits such as irreversibility or cascading effects. The bare statement 'Delete User' provides no extra insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, essentially just restating the tool name. While it contains no fluff, it is under-specified and lacks any structured detail. It is concise but not effectively structured for an agent to understand the operation's implications.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation, the description is insufficiently complete. It does not mention whether the deletion is permanent, if there are any safeguards, or what the consequences are. Although the output schema is absent and complexity is low, the lack of contextual warnings or side effects leaves the agent without critical information when deciding to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'userId' as a path parameter, and the description does not add meaningful information about it. With 100% schema coverage, the baseline is 3, and the description offers no further explanation of the parameter's format, requirements, or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete User' clearly states a specific verb (delete) and resource (user), which is distinguishable from sibling tools like users_get_user and users_update_user. It is concise and unambiguous, though it lacks any additional nuance about the scope or permanence of the deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. For instance, it does not clarify whether this should be used only when a user is no longer needed, or if there are any safety considerations before deleting. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the bare name—it does not explain what the returned call log contains, whether any side effects occur, or what the response format looks like. Given no output schema and no additional detail, the description provides minimal transparency 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single, clear phrase with zero waste. It is front-loaded and efficient, containing no redundant or irrelevant information. While it sacrifices detail, it earns a 5 on conciseness for its minimal, focused structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read operation with annotations covering safety, but the description fails to provide any context about what a call log is, what data it contains, or how the agent should interpret the response. There is no output schema, so the agent is left with only the tool name and a terse description. This is insufficient for confident invocation, especially given the number of sibling tools in the same domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The parameters `callId` ('Call ID') and `locationId` ('Location ID Defaults to GHL_LOCATION_ID when omitted.') are already documented in the schema. The description adds no additional semantic meaning. Per the calibration, a baseline of 3 is appropriate when schema covers the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Call Log' provides a clear verb (get) and resource (call log), satisfying the basic purpose statement. However, it does not differentiate from the sibling tool 'voice_ai_get_call_logs' (plural), so while it is unambiguous about the operation, it fails to indicate whether this tool retrieves a single call log versus multiple. This is a clear but undifferentiated purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not explain when to use this tool versus alternatives, particularly the obvious sibling 'voice_ai_get_call_logs'. There is no mention of prerequisites, filtering, or conditions under which this tool should be selected. An agent would have no basis to decide between singular and plural variants.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and side-effect expectations. The description adds the agency-level token requirement, which is genuine behavioral context beyond annotations. No contradiction exists, but the addition is narrow and does not discuss deprecated versions or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, and the most relevant info is front-loaded. It is appropriately brief for a simple get-by-id operation, though it omits potentially valuable context that could be added without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, readOnly annotations, and no output schema, the description gives the essential operation and an authentication constraint. However, it does not explain what the response contains, whether the companyId must be a specific format, or how this relates to other company resources. It is minimally adequate but leaves meaningful gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for companyId (0% coverage), and the tool description does not explain the parameter at all. While the tool name implies companyId is the identifier of the company to fetch, there is no explicit meaning, format, or scope guidance. With zero schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Company', a clear verb-resource pair that immediately conveys the operation. It also notes the required token type, adding a useful distinction. However, it does not elaborate on what 'Company' means in this domain, and among many sibling get_* tools it is not explicitly differentiated, so it slightly misses the highest clarity bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions an authentication prerequisite (agency-level token vs. location PIT) but provides no guidance on when to choose this tool over alternatives, such as businesses_get_business or other get endpoints. It does not state the typical use case or any preference rules, leaving selection to inference from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. However, the description adds no extra behavioral context—it does not state that the tool returns a list of appointments, whether it includes past/future appointments, or how it handles missing contacts. Given that the annotations cover safety, the description's lack of additional behavioral detail is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only a few words to convey the core action. It is front-loaded with the verb and resource, and there is no redundant information. It earns its place by stating the essential purpose without fluff, though it borders on being too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no nested objects, no output schema), the description is functional but not rich. It does not explain the response format, any filtering options, or potential error conditions. For a simple retrieval tool with annotations providing safety context, this is adequate but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for contactId ('Contact Id') provides 100% coverage, and the tool name itself clearly indicates the parameter's role. The description does not add any further meaning beyond what the schema already communicates. With high schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Appointments for Contact' clearly specifies a verb (Get) and resource (Appointments) scoped to a contact. It immediately distinguishes this tool from other contacts tools like contacts_get_contact or calendars_get_appointment, which focus on different entities. The purpose is unambiguous and matches the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or scenarios where another sibling tool would be more appropriate. An agent is left to infer usage solely from the name and context, which is insufficient for proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds no additional behavioral context beyond the bare action—no mention of permanence, irreversibility, or impact on existing estimates. It relies entirely on annotations for safety cues and provides no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase ('Delete Estimate Template'), which is concise but almost tautological. It does not waste words, but it is so minimal that it contributes little beyond the tool name itself. It is appropriately sized for a simple operation but lacks depth expected of a tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a destructive operation (per annotations) with 3 parameters, but the description provides only the action and resource. It does not explain what an 'estimate template' is, why an agent might need to delete one, or any side effects. Given no output schema and minimal description, an agent has to infer usage entirely from the name and schema, which may be insufficient for a meaningful decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (templateId, altId, altType) already have descriptive entries. The description adds nothing about the parameters. Baseline is 3 because the schema covers the parameters fully; the description does not need to repeat them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and resource ('Estimate Template'), clearly distinguishing it from sibling tools like invoices_create_estimate_template and invoices_delete_estimate. The agent can immediately understand this deletes a template, not an actual estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this deletes a reusable template (as opposed to a specific estimate) or any conditions or prerequisites. There is no mention of when not to use it or how it differs from invoices_delete_invoice_template.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the write nature is known. The description adds the 'max 15 per location' constraint, which is useful context. However, it doesn't disclose failure behavior, permissions, or any side effects beyond creation, so it adds limited value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary detail. It front-loads the action and includes a relevant constraint, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain what the tool returns. It also omits information about the required 'name' parameter and the semantics of 'description'. Given the minimal schema descriptions, this is incomplete for an agent to call correctly without further inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only locationId documented). The description does not explain any parameter semantics, such as what 'name' or 'description' should contain, or how locationId defaults. Since coverage is below 50%, the description fails to compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'knowledge base', and adds a per-location limit. It distinguishes from get/update/delete siblings, but there is an overlapping sibling 'knowledge_base_create' that is not addressed, so it's not perfectly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like knowledge_base_update or knowledge_base_create. The max-15 constraint implies a limit but doesn't explain when not to use it or what to do instead. There's no explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the token requirement, which is useful auth context beyond annotations. However, it does not disclose response format, pagination, or other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no fluff, front-loading the core purpose and a key requirement. It is appropriately concise, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal: it explains the purpose and token requirement but omits any detail about companyId semantics, return data, or relationship to other plan tools. Without an output schema, this is insufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the companyId parameter at all. The agent gets no help understanding what companyId refers to (agency ID, location ID, etc.). This is a critical gap for a single-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get Agency Plans'. It also clarifies the required token type, which distinguishes it from location-level operations. The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a prerequisite (agency-level token, not location PIT) but does not mention when to prefer this tool over siblings like saas_api_get_saas_plan or saas_api_get_location_subscription. No alternatives are named, leaving the agent to infer the correct selection from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, so the description does not need to restate that this is a mutation. However, it adds no new behavioral context—such as whether the deletion is permanent, irreversible, or cascades to associated data. The description is purely redundant with the tool name and annotations, providing no extra transparency beyond what is already structured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—only four words. While it is front-loaded and free of fluff, it is also under-specified, offering no explanatory value beyond the tool name. It is not verbose, but it does not earn points for good structure because it is merely a repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation, the description is incomplete. It lacks any mention of what happens to the action, whether deletion is permanent, or what response to expect (since there is no output schema). Given the tool has three parameters and potential side effects, an agent would benefit from knowing that this is irreversible and possibly warn before calling. The description provides no such context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with clear descriptions (agentId, actionId, locationId including its default). The description adds no additional meaning or syntax details. With full schema coverage, the baseline of 3 is appropriate; the description does not compensate for any gaps because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Agent Action' clearly states a specific verb (delete), a resource (Agent Action), and distinguishes this from sibling tools like voice_ai_update_action and voice_ai_get_action. An agent can immediately understand the tool's function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool, when not to, or what conditions apply. It does not mention alternatives or any prerequisites (e.g., that deleting an action might affect active agents). The description offers no context beyond the operation itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write operation (readOnlyHint=false), not destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds no behavioral context beyond that, such as side effects, authentication requirements, rate limits, or what happens to existing members. While the annotations cover the safety profile, the description could elaborate on the nature of the update (e.g., additive, replacing) but does not. This meets the baseline but adds no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence: 'Batch update audience members'. It is front-loaded with the action and resource, with no filler. It is appropriately sized for what it conveys, though it is minimal. It earns a 4 for efficiency, though it sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters (2 required) and no output schema, the description is critically insufficient. It provides no explanation of the operation types (e.g., add, remove, replace), the role of csvPath, smartlistIds, dynamicAudience, or how the batch process works. An agent cannot infer the correct usage beyond the parameter names, which are not self-explanatory. This is a significant gap for a tool that appears to have complex business logic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions. However, these descriptions are terse (e.g., 'Batch operation type', 'CSV file path', 'Smartlist IDs array'). The tool description does not add any further meaning about how these parameters interact or which are required for which operation. Since the schema already documents the parameters, the description adds no additional semantics, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action 'update' and resource 'audience members', which is specific. It suggests a batch operation, distinguishing it from single-member tools like ad_manager_fb_add_custom_audience_member or ad_manager_fb_remove_custom_audience_member. However, it does not clarify whether the update is adding, removing, or replacing members, nor does it mention the operationType parameter, so it is clear but not fully specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of when to use it instead of the add/remove single-member tools, or the update_custom_audience tool. An agent would have to infer from the name and parameters alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds nothing about what data is returned, authentication needs, rate limits, or any side effects. It is consistent with annotations but provides no additional behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, directly states the action, and contains no fluff. It is appropriately minimal and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter, the description is adequate but minimal. It does not explain what the returned user object contains, any dependencies on integration state, or how 'current' is determined. Given the absence of an output schema and the availability of sibling tools for other platforms, a bit more context (e.g., confirming this is for Facebook's Graph API) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter 'locationId' with a clear description including its default behavior. The tool description does not mention the parameter, but the schema already documents it sufficiently, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'get' and the resource 'current Facebook user', clearly identifying the operation. It distinguishes from similar tools for other platforms (e.g., ad_manager_google_get_current_user) by naming Facebook, though this is already in the tool name. It is concise and unambiguous, though it lacks additional scope details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that this is specific to Facebook, nor does it reference any prerequisite (e.g., having an active Facebook integration) or context like verifying the current authenticated user. An agent gets no help in deciding between this and the Google or LinkedIn counterparts beyond the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no extra behavioral context—e.g., what 'lead forms' includes, whether pagination or filtering is available, or any side effects. With annotations doing the heavy lifting, the description falls short of adding value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, trenchant sentence with zero unnecessary words. It is front-loaded and directly states the action and resource. There is no fluff or repetition, making it an excellent model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two well-documented parameters and safety annotations, the description provides the minimum viable context. However, it lacks any description of the return value or how it differs from similar 'get' tools (e.g., ad_manager_fb_get_lead_form). Given the rich ecosystem of sibling tools, this could lead to incorrect selection, but the schema and annotations partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as both pageId and locationId have descriptive text in the schema. The description itself does not mention parameters, but the schema already documents them adequately. Per the baseline rule, a score of 3 is appropriate when the schema carries the semantic burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get page lead forms' states a clear verb and resource. It is specific enough to identify the tool's function, but it does not differentiate it from similar siblings like ad_manager_fb_get_lead_form (singular) or ad_manager_fb_get_conversation_forms, which could cause ambiguity for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs. alternatives. It does not mention prerequisites, context (e.g., retrieving all lead forms for a page), or any conditions that would favor this tool over sibling 'get' tools. The absence of any usage guidance forces the agent to infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the basic 'get' operation, such as what data is returned, whether pagination applies, or if successful retrieval depends on an existing integration. It does not contradict the annotations, but it also doesn't enrich 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no filler. It gets straight to the point, making it easy to parse. Though extremely brief, it is not unnecessarily verbose, which is a positive for conciseness. It could be slightly more informative without losing structure, but it is well-formed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a simple get operation, the description provides insufficient context. It doesn't mention what the return value looks like (e.g., a list of pixel objects), whether an integration must exist first, or how the optional parameters affect results. For an agent to use this effectively, it needs to know what to expect from the call, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters (pageId, channel, igUserId, locationId) have descriptions. The tool description adds no semantic meaning about how these parameters relate or which are needed. The schema already describes them, so the description provides no additional value here. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get conversion pixels' clearly states the action (get) and the resource (conversion pixels), making the purpose unambiguous. The tool name and description together convey it retrieves conversion pixels within the Facebook ad manager context. It distinguishes itself from sibling get tools by specifying the resource type, though it doesn't elaborate on what a conversion pixel is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or filtering logic. There is no explanation of whether pageId, igUserId, or channel are required or how they interact. An agent would not know when this tool is appropriate compared to other ad_manager_fb_get_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write operation (readOnlyHint=false) and idempotent (idempotentHint=true), which the description's 'Update' verb confirms without adding new behavioral detail. It does not disclose whether it performs a full replacement or partial update, or any side effects. Since annotations cover the basic safety profile, the description adds minimal value but does not contradict 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely succinct ('Update custom audience'), with no unnecessary words. It is front-loaded and efficient. However, it is so brief that it may sacrifice informative value, though that is more a completeness issue than a conciseness problem.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is insufficient for an agent to use the tool correctly. It does not specify that 'name' and 'description' are required fields, what happens to unspecified fields, or any prerequisites (e.g., existing audience, integration). It also omits the optional locationId default behavior. Given the lack of an output schema and the presence of multiple similar tools, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for all four parameters (100% coverage), so the description does not need to explain them. It adds nothing beyond the schema, but the schema already carries the burden. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update') and a specific resource ('custom audience'), which clearly identifies the tool's purpose. However, it does not differentiate from sibling tools like update_campaign or upsert_audience, so it lacks explicit distinction from other update/upsert operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when to use it (e.g., when modifying an existing audience) or when not to use it (e.g., for creation or upsert). No context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the operation's safety profile. The description adds no extra behavioral context, such as what the response contains or any side effects. It does not contradict annotations, and given the annotations' coverage, a middle score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant words. It is efficiently front-loaded with the core action and resource. This is an ideal length for a simple lookup operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a basic get-by-ID operation, the description is minimally adequate. However, it lacks any mention of the return value or what an association is, and it does not differentiate from the many sibling 'get' tools. An agent might struggle to decide when to use this tool versus others without additional context, especially since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for the single parameter 'associationId'. It does not add any explanation of what the ID is or its format. However, the parameter name is self-explanatory (an association identifier), so the lack of description is not severely confusing, but it still doesn't meet the burden of compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does 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 'association' with the qualifier 'by ID'. This distinguishes it from siblings like associations_get_association_by_object_keys or associations_get_association_key_by_key_name, which fetch by different identifiers. While not exhaustive, it is specific enough to convey the primary action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool over the many other association-related tools. It does not mention alternatives, exclusions, or any context that would help an agent choose this specific 'by ID' variant versus the 'by object keys' version. This is a significant gap given the large sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, meaning the tool mutates state, and the description's verb 'Add' is consistent. No contradiction found. The description doesn't disclose additional behavioral details like side effects, permission requirements, or the fact that it appends a call message to a conversation, but since annotations cover the mutability, the bar is lower. It adds minimal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, terse sentence with no fluff—'Add an external outbound call'. It is front-loaded with the core action, but given the tool's complexity (7 parameters, nested objects), it is arguably too sparse to be adequately structured. It earns credit for brevity and clarity but lacks the substance needed for a helper description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and only 3 annotations (none of which are rich in behavior), the description is severely under-specified. It doesn't explain what 'external' means, whether it creates a conversation message, how the 'call' object relates to the 'type' enum, or any side effects. The minimal annotation coverage leaves the description as the primary guidance, and it is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—every parameter has a description in the schema, including the nested 'call' object and its subfields. The tool description adds no parameter-specific meaning beyond what the schema already provides. Since coverage is high, a baseline of 3 is appropriate, and the description doesn't compensate or enhance the schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add an external outbound call' uses a specific action verb and resource, clearly indicating it creates a call record. It differentiates from the sibling 'conversations_add_an_inbound_message' by specifying 'outbound', but doesn't elaborate on what 'external' means relative to other messaging tools. The name suggests a message while the description says call, introducing slight ambiguity, but the overall intent is discernible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'conversations_add_an_inbound_message' or 'conversations_send_a_new_message'. It lacks any context about prerequisites, scenarios, or exclusions. While the name hints at outbound calls, there is no explicit routing or differentiation advice.
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 annotations already convey readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds minimal behavioral context—it does not state what format the downloaded transcription takes (e.g., file, text) or any side effects. Since annotations cover the safety aspects, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no wasted words. It is front-loaded with the primary action and identifier, making it easy to scan. Slightly more detail on output would be useful, but the brevity is a strength.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not clarify what the 'download' actually returns—whether it is a file, text, or a URL. It also lacks context about the relationship to message recordings or transcriptions. For a simple read operation, the description could be considered minimal but leaves an agent uncertain about the response format, which is a functional gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so both parameters (messageId and locationId) already have descriptions in the input schema. The description mentions messageId but not locationId, adding only marginal emphasis. As the schema fully documents parameters, the description does not need to add much; baseline 3 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Download transcription by Message ID' clearly states the action (download) and resource (transcription) with the key identifier (Message ID). It is specific enough to understand the core function, but does not differentiate from the sibling conversations_get_message_transcription, which may overlap in intent. The name 'download' vs 'get' hints at a file retrieval but is not explicitly clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling conversations_get_message_transcription or conversations_get_message_recording. There is no mention of prerequisites, scenarios, or exclusions. An agent is left to infer which tool to choose based solely on the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only (readOnlyHint=false) and not idempotent, but the description adds little beyond stating an 'indicator'. It does not disclose the side effects (e.g., whether it actually sends a typing status to the client, whether it requires an active connection, or whether it overrides existing statuses). With annotations covering some aspects, the description should contextualize the behavior but fails to do so.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It states the core purpose efficiently, and while it could be more detailed, it is not bloated. It earns its place by clarifying the domain (agent/bot typing indicator) beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool (readOnlyHint=false) with no output schema, the description should clarify the effect and any prerequisites. It only vaguely mentions an 'indicator' without explaining how the parameters interact (e.g., what does 'isTyping' accept? Does visitorId/conversationId identify the chat context?). The description is insufficient for an agent to correctly invoke the tool without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters have descriptions, but some are vague (e.g., isTyping just says 'Typing status' without specifying valid values, such as boolean or string enums). The tool description adds nothing beyond the schema, so it meets the baseline of 3 for high coverage without adding extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear purpose: 'Agent/Ai-Bot is typing a message indicator for live chat' – it indicates the tool signals a typing status. It is specific enough to distinguish it from other conversation tools (no other typing tool exists among siblings), though it could be more explicit about the action being performed (e.g., 'use this to send a typing indicator').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this when you want to indicate that an agent/bot is typing in a live chat. However, there is no explicit guidance on when to use vs. alternatives, nor any note about prerequisites. Since no sibling tool covers typing, the ambiguity is low, but the description still lacks explicit 'when to use' clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds no additional behavioral context (e.g., that it posts publicly, may overwrite existing replies, or requires specific permissions). For a write operation targeting an external system (Google My Business), this lack of detail is a gap, though not a 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no fluff. It is front-loaded with the core action and target, making it easy to parse. No unnecessary words or repetitive information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, all documented in the schema, the description is adequate but incomplete. It doesn't mention potential side effects, error conditions, or when it should not be used (e.g., only for conversations tied to Google My Business reviews). The schema fills some gaps, but the lack of behavioral context lowers completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having descriptive text (e.g., conversationId 'must have reviewId', locationId defaults to GHL_LOCATION_ID). The description adds no extra meaning to parameters, so it relies entirely on the schema, which is adequate but not enhanced by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Send') and resource ('review reply') with a clear target ('Google My Business'). It is unambiguous and distinguishable from other conversation tools by the 'Google My Business' qualifier, though it doesn't explicitly differentiate from conversations_send_a_new_message or similar tools without requiring inference from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like conversations_send_a_new_message or other review-related tools. It lacks any conditions, exclusions, or references to sibling tools, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds no additional behavioral context, such as return format, error handling, or edge cases, beyond restating the tool's purpose. With annotations present, the description's lack of extra detail is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, 'Get Custom Field / Folder By Id', which is concise and front-loaded with the essential action. Every word serves a purpose, and there is no redundant elaboration or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward get-by-id tool with a single parameter and no output schema, the description is minimally sufficient. However, it does not clarify whether the tool returns a field or a folder, nor does it address potential ambiguity in the resource type. Missing details about return structure or error conditions are not critical but leave some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented 'id' parameter. The description merely says 'By Id', which reiterates that the parameter is an ID but adds no information about ID format, type expectations, or what constitutes a valid ID. For a single simple parameter, this is barely adequate but fails to provide meaningful semantic enrichment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource as 'Custom Field / Folder', which clearly indicates fetching a single custom field or folder by ID. It is distinguishable from siblings like custom_fields_create_custom_field or custom_fields_delete_custom_field, though it does not specify whether the ID refers to a field or folder, introducing slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It is implied that this is the correct tool when retrieving a custom field or folder by its ID, but no conditions or exclusions are stated. Given the obvious purpose, this is sufficient for a simple get-by-id operation but lacks explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: false, idempotentHint: true, and destructiveHint: false, so the safety profile is covered. The description does not add any behavioral details beyond what annotations provide, such as side effects, permission needs, or impact on associated fields. It does not contradict annotations, but it also does not enrich 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase with no filler words. It is well-structured and easy to parse, but it is extremely terse and lacks any additional context that could be valuable without being verbose. It is appropriately concise, though it does not take advantage of the space to add clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update operation with no output schema, the description is minimal. It does not explain what the update entails (e.g., renaming a folder), whether it returns anything, or other operational details. The schema requires 'id' and 'name', but the description does not help an agent understand the effect of the operation or any caveats. This is insufficient for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% — the 'name' and 'locationId' parameters have descriptions, while 'id' does not. The tool description adds no parameter-level guidance, and it does not compensate for the undocumented 'id'. The schema carries most of the semantic load, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update Custom Field Folder Name' clearly states the verb (update) and the object (custom field folder name). It is distinct from sibling tools like custom_fields_create_custom_field_folder or custom_fields_delete_custom_field_folder, and from custom_fields_update_custom_field which targets a field, not a folder. However, it does not elaborate on what a folder is or any nuances, so it is clear but not fully differentiated beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites (e.g., existing folder id), no context about typical use cases, and no exclusion criteria. The description does not help an agent decide between this and related update/create/delete folder tools beyond the implied operation.
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 the token requirement, which is useful behavioral context not present in annotations. Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description does not contradict these. However, it does not disclose other behavior such as whether the update is partial or full, or what the response contains, but given annotation coverage, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and adds a key constraint. It is efficient with no fluff, but it lacks additional context that could be inserted without bloating, making it appropriately sized for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters, nested objects, and no output schema, the description is notably thin. It only mentions the token requirement and does not provide guidance on how to structure updates (e.g., when to set locations vs showOnCompany), or what the expected return is. Even though the schema has descriptions, the description fails to add operational context that an agent would need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning the schema already documents all 12 parameters. The description adds no additional parameter semantics. Per rubric, baseline is 3 when coverage is high, and the description does not enhance understanding of parameters like the relationship between locations, showOnLocation, and showToAllLocations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update Custom Menu Link' which clearly identifies the action (update) and resource (custom menu link). It distinguishes from sibling create/delete/get operations by its verb. However, it uses 'Link' rather than the broader 'Custom Menu' which might slightly narrow the scope, but it's still clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical prerequisite (agency-level token, not location PIT) but offers no guidance on when to use this tool versus alternatives like create/delete/get custom menus. It does not mention typical use cases or scenarios, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds no behavioral details beyond the annotations—no mention of pagination, result format, or any operational constraints. It is consistent with annotations but provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two words with no extraneous content. It is front-loaded and efficient, although it is possibly too terse to convey necessary context. Given its minimal length, it earns a high score for conciseness and structure, but not a perfect 5 because it omits potentially important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, including required limit and offset, and no output schema, the description should explain return values, pagination, or usage context. It does none of this. The tool is relatively complex, and the description is inadequate for an agent to call it correctly without additional documentation. It only states the action without any contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the 12 parameters having a description, including enums and defaults. The description itself does not add any parameter-related meaning, so it relies entirely on the schema. Since coverage is high, the baseline of 3 is appropriate; the description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List invoices' clearly identifies the verb (list) and resource (invoices), distinguishing it from get_invoice, create_invoice, and other sibling invoice tools. However, it does not provide any additional scoping or filtering context that would help differentiate it from other list operations, so it is clear but not exceptionally specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any use cases, exclusions, or conditions, and it does not reference any sibling tools like invoices_get_invoice or invoices_list_estimates. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the token requirement, which is useful. Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) already provide some behavioral context, so the bar is lower. However, the description fails to disclose whether the operation creates or updates a sub-account, which is a key 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, efficiently combining the operation name and auth requirement. It is front-loaded and has no wasted words. However, it may be too terse for the tool's complexity, but that's a completeness issue, not a conciseness one.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 17 parameters, nested objects, and no output schema, the description is drastically under-specified. It doesn't mention that locationId likely determines create vs update, doesn't explain the required companyId, or the overall effect of the operation. The description is not complete enough for an agent to understand the tool's behavior beyond its name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 94%, so parameters are well-described in the schema. The description itself adds zero parameter-specific information, so it doesn't add value 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Put Sub-Account (Formerly Location)' which is specific. However, it doesn't differentiate this from potential siblings like locations_create_location or locations_update_location, as there is no explicit mention of create vs update semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the authentication prerequisite ('requires an agency-level token, not a location PIT'). There is no indication of when to use this tool versus alternatives, no mention that it can create or update based on locationId, and no exclusions or context on scenarios. This leaves the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no extra behavioral context (e.g., pagination, sorting implications, or that it returns a list without filters). It doesn't contradict annotations, but it also doesn't enrich them with any additional behavior, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that states the core action. It is not verbose and is front-loaded with the verb. However, it is arguably too minimal to be fully helpful, but for conciseness alone it earns a 4 since every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters (3 required) and no output schema, the description is severely lacking in context. It does not explain how to use the parameters, what values are expected (e.g., 'type' likely expects 'file' or 'folder'), how to construct a valid request, or what the response looks like. An agent would struggle to call this correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a basic description. The tool description adds no additional meaning about parameters—it does not clarify expected values, relationships, or defaults beyond what the schema provides. Baseline of 3 applies because the schema does the heavy lifting, but the descriptions are generic (e.g., 'Type' without allowed values).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('List of Files/ Folders'), which distinguishes it from sibling tools that create, update, or delete media objects. However, it doesn't specify the exact output format or scope beyond 'files/folders', so it's clear but not highly detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention when to prefer this over other media tools (e.g., when to use medias_bulk_delete_media_objects) or any context for use. It merely states the action without indicating scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no behavioral detail beyond the verb 'disconnect' — it doesn't state whether the operation is reversible, what state changes occur, or any side effects. Since annotations carry the safety profile but leave the impact ambiguous, the description fails to enrich 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero redundancy. It efficiently communicates the core operation without unnecessary detail, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with high schema coverage, the description is minimally adequate. However, it lacks context on what 'provider config' refers to, what the expected outcome is, and doesn't differentiate from the nearby payments_integration tools. An agent might need to inspect sibling definitions to fully understand when this is the right call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: liveMode and locationId each have descriptive text explaining their meaning and defaults. The description contributes no additional parameter insight, so it meets the baseline for high schema coverage but doesn't go beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'disconnect' and the resource 'provider config', making the primary action clear. It distinguishes itself from create/fetch config siblings through the unique verb, though it doesn't explicitly contrast with payments_delete_integration, which could be a closely related alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like payments_create_config, payments_fetch_config, or payments_delete_integration. It doesn't mention prerequisites, such as needing an existing config, or when disconnecting (vs deleting) is appropriate. The agent is left to infer the usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no behavioral details beyond these hints—it does not clarify response format, error handling, or authentication requirements. Since the annotations carry the informational burden, the description meets the baseline but adds no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single fragment—which is appropriate for a simple get-by-id operation. However, it essentially restates the tool name without adding explanatory value. It is not verbose, but it is under-specified in a way that does not earn a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, full parameter coverage in the schema, and comprehensive annotations, the description is minimally sufficient. There is no output schema, so return value details are not required. However, the absence of any usage context or alternative routing makes it slightly incomplete for an agent that needs to decide among similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (orderId, altId, locationId) are fully documented in the schema. The description does not add any parameter semantics beyond what the schema already provides, which is acceptable given the high coverage. No additional insight is needed or offered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Order by ID' clearly states the verb (get) and resource (order), with the scope being by ID. It is unambiguous about what the tool does, but it does not differentiate it from other get-by-id tools in the same namespace (e.g., payments_get_subscription_by_id, payments_get_transaction_by_id). The name already conveys this, so it works but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like payments_list_orders or other get-by-id tools. There is no mention of context, prerequisites, or fallbacks. The description offers no usage context, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. However, the description adds no behavioral context such as what the returned list contains, whether pagination is supported, or any filtering nuances. With the bar lowered by annotations, this still falls short because it contributes no additional behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase with no wasted words. It is appropriately sized for a simple read-only list operation, and the front-loaded verb and resource make it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only one optional parameter, no output schema, and safety annotations covering the read-only nature, the description is minimally adequate. However, it omits any mention of return format, pagination, or how the returned list is structured, which could be important for an agent to correctly consume the result. It is complete enough for a trivial call but lacks richness expected of a well-documented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description contains no parameter information at all. The schema fully documents the optional locationId with its default behavior, so the description adds no value 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Number Pools' clearly states an action (list) and a resource (Number Pools). It is not a tautology and distinguishes itself from other phone_system tools like phone_system_active_numbers or phone_system_purchase_phone_number, though it does not explicitly compare to them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions. An agent would have to infer usage from the meaning of 'Number Pools' alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation) and idempotentHint=false, which the description implicitly agrees with by saying 'purchase'. However, the description adds no extra behavioral context such as billing implications, compliance requirements, or consequences of repeated calls. It does not contradict annotations, but it doesn't enrich them beyond the basic mutation implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded and easy to parse. However, it is arguably too terse for a tool with 10 parameters and compliance aspects, so it could benefit from a slightly expanded structure. Still, it earns a 4 for being direct and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, regulatory SIDs, KYC flags) and lack of output schema, the description is far too minimal. It doesn't mention what the tool returns, prerequisites like compliance documents, or common pitfalls (e.g., number unavailability). The annotations provide no additional context. An agent cannot fully understand the tool's behavior from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 10 parameters are documented in the schema. The description adds no additional meaning to the parameters. With full coverage, the baseline is 3, and since the description offers no extra clarification or grouping, it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'purchase' and the resource 'phone number', clearly stating the tool's action. It distinguishes from siblings like phone_system_available_numbers (which lists purchasable numbers) and phone_system_active_numbers (which lists current numbers) by implying the purchase action, though it doesn't explicitly mention those distinctions. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like phone_system_available_numbers or phone_system_active_numbers. There is no mention of prerequisites, conditions, or exclusions. An agent would have to infer from the tool name and siblings. This is a clear gap for a 10-parameter tool with regulatory implications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds no behavioral context beyond what the annotations provide. The description does not disclose any side effects, required preconditions, or return behavior. For a creation tool with complex schema, it adds nothing beyond the verb itself, which is redundant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is appropriately front-loaded and minimal, which is good for efficiency. However, it may be too terse, but conciseness is not penalized for brevity alone; it is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 23 parameters, nested objects, and no output schema, the description provides almost no contextual guidance. It doesn't explain the domain of pricing, the meaning of a price in relation to a product, or any usage context beyond the bare action. An agent would need to rely entirely on the schema and sibling names to understand what is expected. This is a significant gap for such a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning every parameter already has a description in the schema. The tool description does not add any additional semantic meaning to any parameter; it only states the general purpose. Therefore, the baseline score of 3 applies because the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and resource ('Price for a Product'), which clearly distinguishes it from sibling tools like products_get_price_by_id_for_product, products_update_price_by_id_for_product, and products_delete_price_by_id_for_product. The purpose is unambiguous and directly aligns with the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description simply states the action without any context about prerequisites, typical scenarios, or exclusions. An agent is left to infer from the schema and sibling names that this is the creation tool for prices, but no explicit usage guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Delete', which aligns with the destructiveHint annotation but adds no additional behavioral context like irreversibility, cascading effects, or required permissions. With annotations already covering destructive and idempotent behavior, the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys the essential action without unnecessary words. It is appropriately concise for a straightforward delete operation and is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with full schema coverage and annotations declaring destructive and idempotent behavior, the description is minimally adequate. However, it could be improved by mentioning consequences of deletion (e.g., what happens to associated data) or expected response, since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are already documented in the input schema. The description does not add any additional meaning about how parameters interact or their significance, keeping this at the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Product Collection' clearly states a specific action and resource, distinguishing it from siblings like products_delete_product_by_id. However, it is minimal and doesn't elaborate on scope or exact behavior, so it falls slightly short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as deleting a product or price. No conditions, prerequisites, or exclusions are provided, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, indicating a non-idempotent, mutating operation. The description adds the authentication requirement (agency-level token), which is useful operational context. However, it does not disclose side effects like billing changes or irreversibility, but given the annotations cover the mutation aspect, the added auth detail earns a middle score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence stating the purpose and a key prerequisite. No fluff, no redundancy. It is appropriately concise, though it might be too brief to be fully helpful—but for the information it chooses to include, it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutating, non-idempotent tool with 4 required parameters including a nested object, and no output schema, the description is notably sparse. It does not explain the business effect (enabling SaaS for locations), what the actionPayload represents beyond the schema, likely side effects, or what the response will be. An agent would have to infer most operational context from the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (companyId lacks a description). The description adds no parameter explanations, but the schema already describes locationIds, isSaaSV2, and actionPayload. Since coverage is moderately high, the description is not required to compensate. The missing companyId semantics are a gap, but the baseline for this coverage is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Bulk Enable SaaS'. It conveys that this is a bulk operation, which is consistent with the schema's locationIds array. It also adds a distinguishing detail (agency-level token, not location PIT) that separates it from location-scoped operations. However, it does not explicitly mention that it applies to multiple locations or contrast with the deprecated or disable variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite (agency-level token) but no guidance on when to use this tool versus alternatives like saas_api_bulk_disable_saas or saas_api_enable_saas_location. It does not say 'use this for bulk operations' or mention the deprecated sibling. The token requirement implicitly says if you don't have an agency token, you shouldn't use it, but that's the only guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior. The description adds the critical token requirement, which is useful. However, it doesn't describe side effects, reversibility, or what happens to existing rebilling settings when this is called, which would be valuable for an update 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler, and it front-loads the purpose before the token caveat. It is appropriately brief, though it could add a little more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation with four parameters (including nested config) and no output schema, the description is under-specified. It omits the fact that it operates on multiple locations (though schema implies it) and doesn't explain what 'updating rebilling' affects (e.g., billing, tokens, product eligibility). An agent would need to inspect the schema and infer behavior, which is inadequate for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents three of four parameters with descriptions (config, product, locationIds), and coverage is 75%. The description adds no parameter-specific information beyond the token requirement, which is not a schema parameter. Since the schema does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('Update Rebilling') with a clear verb and resource, and it is distinct from sibling tools like enable/disable or deprecated versions. However, it doesn't specify what 'Rebilling' entails beyond the name, relying on the schema for details like config fields and location scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (agency-level token) but no guidance on when to use this tool versus alternatives such as enabling/disabling SaaS or other rebilling-related endpoints. There is no mention of scenarios or conditions that would select this tool, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds the auth requirement (agency-level token), which is contextual but not behavioral. It doesn't disclose what fields are updated, whether the update is partial or full, or any consequences. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the main action front-loaded and the key prerequisite included. No wasted words, though it lacks additional helpful details, which is a minor cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no output schema, the description is minimal. It doesn't explain what 'update' entails, what fields are mutable, return behavior, or how the locationId default works (though schema covers the default). The token requirement is useful, but for a 4-parameter tool with no output schema, this is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – all four parameters have descriptions, including the default for locationId. The description adds no extra semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Update SaaS subscription') and adds an important prerequisite (agency-level token). It doesn't differentiate from sibling tools like update_rebilling or the non-deprecated counterpart, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is the token requirement ('requires an agency-level token, not a location PIT'), which is a prerequisite but not guidance on when to choose this tool vs alternatives. No mention of when not to use, deprecation status implications, or when to prefer the non-deprecated version. The guidance is essentially an access condition, not usage selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context, such as what the OAuth flow returns (e.g., a URL), whether user interaction is required, or side effects. It fails to explain the mechanism beyond the bare fact it starts OAuth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It is effectively front-loaded with the core verb and object. However, it is under-specified as a result, so while concise, it lacks richness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an OAuth initiation tool with no output schema, the description should explain expected outcomes or return values. It does not mention redirects, authorization URLs, or any subsequent steps. Given the existence of a sibling 'start_tiktok_oauth', the description should clarify the business vs. personal distinction, but it only implies it. Incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are described in the schema. The description adds no extra semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate because the schema carries the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Starts OAuth') and resource ('TikTok Business Account'), and the 'Business' qualifier distinguishes it from the sibling 'start_tiktok_oauth' (presumably personal). It leaves no ambiguity about the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. The description implies business account usage, but does not state conditions or exclusions, nor does it mention sibling tools. An agent must infer the distinction from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose destructiveHint=true and idempotentHint=true, so the description is not required to repeat those. The description adds no extra behavioral context such as permanence or effects on related entities, but it is consistent with the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient phrase 'Delete custom audience' with no wasted words. It is front-loaded and immediately conveys the action, though it lacks any supplementary detail that could enhance clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation (delete by ID), the annotations covering destructive and idempotent behavior, and the schema documenting all parameters, the description is sufficient for an agent to invoke the tool correctly. No return value is needed, and no complex caveats are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for both parameters (audienceId and locationId). The description adds no parameter-specific semantics beyond what the schema already states, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete') and a specific resource ('custom audience'), which clearly identifies the operation. It is unambiguous and distinct from siblings like 'ad_manager_fb_remove_custom_audience_member' or 'ad_manager_fb_update_custom_audience'. However, it does not explicitly contrast with similar delete tools, so it is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of appropriate contexts. An agent receives no instructions for selection or exclusions, so it earns a low score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description is consistent but adds no extra behavioral context, such as whether the deletion is permanent, what related data is affected, or 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no redundant words, front-loaded with the core action. It is concise, though it borders on under-specification because it repeats the tool name without adding detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, but the description lacks context about side effects, reversibility, or any required permissions. While annotations cover destructiveness, the description itself is thin and could benefit from stating the impact of deletion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents locationId with its default. The description adds no parameter-level meaning, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Delete' and the resource 'Facebook integration', which clearly matches the tool name. It distinguishes from other integration tools (e.g., ad_manager_fb_create_integration) by naming the specific platform, though it doesn't elaborate on the scope or consequences of deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, and no conditions under which deletion is appropriate. The description provides no context about when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that the tool returns 'linked entities,' which is a behavioral detail beyond what annotations provide, but it does not disclose what those entities are or any other side effects or error 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that fronts the main action and object. There is zero wasted wording, and it conveys the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what 'linked entities' means and the structure of the returned data. It does not, so an agent may be uncertain about the response format or the extent of the included entities. For a tool that can return complex nested campaign data, this description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all four parameters (100% coverage), so the baseline is 3. The tool description adds no additional meaning about parameters—it does not explain how 'fields' affects the response or what 'source' denotes, leaving the parameter descriptions to stand alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get campaign with linked entities,' which clearly identifies the verb (Get) and resource (campaign), and adds scope ('linked entities'). This distinguishes it from sibling tools like ad_manager_fb_get_campaign_reporting or ad_manager_fb_get_entity, though it does not enumerate which linked entities are included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives, no context scenarios, and no mention of when not to use it. The description relies solely on the tool name to imply its use case, which is insufficient for an agent to decide between the many sibling ad_manager_fb_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond that minimal safety picture, but with annotations doing the heavy lifting, the bar is met. It does not describe what a conversation form is or any kind of filtering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no wasted words and clear front-loading of the action. Efficient for a simple read-only tool, though slightly over-terse in that it omits any distinguishing context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with 1 optional parameter, no output schema, and annotations covering safety. However, it lacks any explanation of what conversation forms are, how they relate to Facebook ad pages, or how this differs from lead-form retrieval, leaving some ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the single locationId parameter already documented ('Location identifier Defaults to GHL_LOCATION_ID when omitted'). The description adds nothing about parameters, so the baseline 3 applies since the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb-resource pair ('Get conversation forms') that adequately conveys the operation. However, it does not differentiate from adjacent siblings like ad_manager_fb_get_page_lead_forms and ad_manager_fb_get_lead_form, which an agent could easily confuse with conversation forms. The description is clear but borders on merely expanding the tool name suffix.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives (e.g., get_lead_form vs. get_page_lead_forms vs. get_conversation_forms). No exclusions, no context about which Facebook object this maps to, and no mention of prerequisites such as a configured integration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context, such as what happens if the lead form is not found or the structure of the response. This is acceptable given the annotations but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no fluff. It is efficient for a simple read operation, though it borders on under-specification. It earns a 4 for being concise without redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation with no output schema, the description is minimally adequate. However, it does not mention that it returns a single lead form or hint at the response format. Given the existence of sibling list tools, a note about singular vs. plural would improve completeness. It's functional but not generous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and both parameters are described in the input schema: leadFormId ('Lead form identifier') and locationId ('Location identifier Defaults to GHL_LOCATION_ID when omitted.'). The description adds no further meaning, so it relies on the schema. The baseline of 3 applies because coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get lead form by ID' clearly states the action (get) and the resource (lead form) with a specific identifier. It is distinct from listing or creating operations, but it does not explicitly differentiate from similar 'get lead form' tools across platforms (e.g., ad_manager_li_get_lead_forms) beyond the tool name prefix.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The agent is not told that this fetches a single lead form by ID whereas other siblings like ad_manager_fb_get_page_lead_forms list all forms. The description lacks any context on prerequisites or intended use 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing about behavior such as response format, pagination, or default location handling (locationId defaults to GHL_LOCATION_ID), but it is consistent with the annotations. With annotations present, the minimal description is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler or redundancy. It is front-loaded with the core action. While it is terse, it is efficient and well-structured for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity get-by-ID tool with one required parameter, high schema coverage, and read-only/idempotent annotations, the description is minimally sufficient. However, it does not mention the optional locationId parameter's default behavior or any specifics about the returned object, and there is no output schema to clarify the response. Given the low complexity, this is acceptable but leaves some gaps an agent might need to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both locationId and conversionId clearly described in the schema. The description 'Get conversion by ID' adds no parameter meaning beyond what the schema already provides. Per the rubric, with high schema coverage, the baseline is 3, and no additional value is contributed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states a specific verb ('Get') and resource ('conversion') with the retrieval criterion ('by ID'). The purpose is unambiguous, though it does not differentiate from sibling tools like ad_manager_google_get_conversions which might also return conversion data. The tool name itself provides clarity, but the description adds little beyond a restatement of the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of when to prefer fetching a single conversion vs listing conversions, nor any prerequisites (e.g., integration setup). The name implies usage, but the description offers no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no behavioral context beyond what annotations provide — no auth requirements, return format, or side-effect notes. Since annotations carry the burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste — appropriate for a trivial read tool. Nothing extraneous, though it is at the absolute minimum viable length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, safe, idempotent read with one optional parameter fully documented in the schema and annotations covering the safety profile, the description is mostly adequate. However, it offers no guidance on what the integration data looks like or when it might not exist, which slightly detracts from completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single optional parameter locationId is already documented in the schema ('Location identifier Defaults to GHL_LOCATION_ID when omitted'). The description adds no meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get LinkedIn integration'. It clearly distinguishes itself from siblings like ad_manager_fb_get_integration and ad_manager_google_get_integration through the 'li' platform prefix, and from ad_manager_li_create_integration through the get/create contrast. Clear but minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is provided. There is no mention of when to call this vs. creating an integration, nor any exclusions. The read-only nature is implied only by the verb, and the locationId default behavior is documented only in the schema, not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context, such as pagination behavior, response format, or any side effects. It provides no value beyond what annotations already state, and therefore scores low on this dimension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence with zero waste. The verb 'List' is front-loaded, and every word contributes to the meaning. It is concise and well-structured for an efficient scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the operation (one required parameter, no output schema), the description is minimally adequate but lacks any detail about the response or any filtering options. A simple list tool might be sufficiently described with this, but the absence of any mention of pagination or the nature of the actions returned leaves some ambiguity. It is complete enough for a trivial case but not robust.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not compensate. The only parameter, agentId, is not explained beyond its name. The phrase 'for an Agent' hints at the purpose, but there is no detail about format, whether it is required, or any validation. With low coverage, the description should add more semantic meaning but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description "List Actions for an Agent" clearly states the verb (list), the resource (actions), and the context (for an agent). It distinguishes itself from sibling tools like conversation_ai_get_action_by_id (which retrieves a single action) and conversation_ai_create_action (which creates actions) by using the plural 'Actions' and the 'List' verb. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this should be used to retrieve all actions for an agent as opposed to getting a specific action via conversation_ai_get_action_by_id. There is no explicit or implicit comparison to other tools, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, clearly indicating this is a mutating operation. The description 'Cancel a scheduled message' is consistent with these annotations and adds no additional behavioral context (e.g., permanence, reversibility, or side effects). Since the annotations cover the key behavioral traits, the description adds minimal incremental value but does not contradict 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler words. It is front-loaded with the essential action and object. Every word earns its place, and there is no redundancy or ambiguity. This is an example of efficient, minimal prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of a sibling tool conversations_cancel_scheduled_email_message, the description fails to clarify whether this tool handles only non-email scheduled messages or all types. It also omits any note about idempotency (though annotated) or potential error cases. For a simple cancellation operation with a single parameter, the description is minimal but leaves the scope ambiguous, making it incomplete for an agent navigating a large tool set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a single parameter messageId with a trivial description 'Message Id'. Schema description coverage is 100%, so the schema already documents the parameter. The tool description adds nothing to clarify the parameter's format, origin, or constraints. With full schema coverage, the baseline is 3, and the description does not enhance it further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb-action ('Cancel') and a specific resource ('a scheduled message'), which is unambiguous. However, it does not differentiate from the closely related sibling tool conversations_cancel_scheduled_email_message, which cancels a specific subtype. Without explicit distinction, an agent might conflate the two, though the naming does provide a hint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the sibling conversations_cancel_scheduled_email_message or any other alternative. It does not mention prerequisites, conditions, or scenarios where cancellation is applicable. The agent is left to infer the scope and intent from the name alone, which is insufficient for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which cover the safety profile. The description provides no additional behavioral context beyond what annotations state — it does not describe the return format, the effect of omitting email, or any potential edge cases. Since the description adds no value beyond the annotations, it falls short of the lowered bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, being just a short phrase. It is appropriately sized for a simple tool and contains no unnecessary wording. However, it is essentially a repetition of the title/name, offering no extra structural benefit, yet it is not verbose or bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with 3 parameters, and given that the schema covers all parameters and annotations cover safety, the description is minimally sufficient. However, there is no output schema, so the description does not hint at the return structure. The missing piece is the response format, which would help the agent understand what to expect, but the tool's low complexity keeps the gap modest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters have descriptions), so the schema already documents the parameters. The description adds no additional parameter meaning. According to the rubric, when schema coverage is high, a baseline of 3 is appropriate, and this description does not exceed that baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get Contact Unsubscription Status'. It is specific enough to indicate the operation is fetching unsubscription status for a contact. It does not explicitly differentiate from sibling tools, but none of the siblings appear to perform the same function, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit instructions on when to use this tool versus alternatives, but the name and parameter schema make it the obvious choice for checking unsubscription status. Siblings are mostly unrelated (ad management, invoices, etc.), so the usage context is implicitly clear, yet no explicit when/when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description simply repeats the action without adding context such as whether deletion is permanent, irreversible, or has cascading effects. It does not contradict annotations, but it adds no behavioral insight beyond what the annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise and front-loaded. It avoids fluff and communicates the core action immediately. However, it is so brief that it omits any clarifying context, though for a simple delete operation this may be acceptable. It earns its place but could be slightly richer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single required parameter and two optional ones, all well-documented in the schema. Annotations cover destructive and idempotent behavior. However, the description fails to differentiate from the void invoice sibling, which is a key decision point. An agent might not know whether to call this or void, limiting completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (invoiceId, altId, altType). The tool description adds no additional semantic details about these parameters, such as format, constraints, or how altId/altType relate. Since the schema already documents them, the description contributes nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('invoice'), making the primary purpose unambiguous. However, it does not differentiate from sibling tools like invoices_void_invoice or invoices_delete_invoice_schedule, which could be confused with this operation. The purpose is clear but not distinctly framed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Given the existence of invoices_void_invoice and other delete operations, an agent receives no hints about prerequisites, conditions, or when deletion is appropriate instead of voiding. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), and the description adds that it is a 'manual payment', providing slight context. However, it does not disclose side effects such as whether the invoice status changes, or if any confirmation is generated, relying solely on the annotation to convey mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no waste, and the action is front-loaded. While it is very brief, it is appropriately concise for a tool description, though it could arguably benefit from a bit more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters and nested objects, the description is insufficient. It does not explain return behavior (though no output schema exists), prerequisites, or typical usage flow. An agent would have to rely entirely on the schema, and even then, the description doesn't clarify the purpose of each field or how they interact, leaving it incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not reference any parameters; the schema already covers 73% of parameters with descriptions. Since coverage is only moderate, the description could have added guidance on required parameters like invoiceId and mode, but it is completely silent on them, providing no additional value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Record a manual payment') on a specific resource ('an invoice'). It clearly differentiates from sibling tools like invoices_create_invoice (which creates an invoice) and payments_record_order_payment (which records order payments), leaving little ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions, so an agent must infer the appropriate context from the name alone, which is insufficient given the large set of invoice-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Delete' aligns consistently with these. The description adds no extra behavioral context beyond what the annotations provide (e.g., no cascading effects or consequences of deletion), but given the annotations carry the safety profile, the bar is lower and a 3 is appropriate. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The two-word description contains zero waste and is appropriately minimal for a single-parameter destructive tool. It is concise rather than under-specified, though it borders on being too sparse to add value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with full annotation coverage, no output schema, and a self-documenting schema, the description is adequate. The name, schema, and annotations together provide enough for an agent to call the tool correctly, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with linkId documented as 'Link Id' in the schema. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Link' names a specific verb (delete) and resource (link), so it is technically clear what action is performed. However, it adds nothing beyond what the tool name already conveys and does not differentiate among the link siblings (links_create_link, links_update_link) beyond the verb, which is already evident from the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as links_update_link or links_create_link. There is no mention of prerequisites, context, or conditions that should trigger deletion, leaving the agent to infer usage on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint and idempotentHint, which match the verb 'DELETE'. The description adds no additional behavioral context (e.g., irreversibility, effects), but it is consistent with annotations and does not contradict 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action verb. It is efficient and to the point, though it could be slightly more descriptive without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description is minimally sufficient, but it omits any mention of location scope, irreversibility, or any side effects. Given the availability of similar sibling tools, a bit more context would help disambiguate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented (id and locationId). The description adds no extra meaning about parameter usage or relationships beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (DELETE) and the resource (email/sms template). It is specific enough to distinguish from other delete operations by name, though it does not explicitly mention the location scope that the tool name implies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as emails_delete_template or other template deletion tools. The description provides no context about the appropriate scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small but useful clarification that 'Sub-Account' was formerly called 'Location', which aids understanding of domain terminology. No additional behavioral traits (like return format or pagination) are disclosed, but for a simple get operation this is acceptable given 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single phrase that conveys the essential purpose. It is front-loaded and efficient with no wasted words. While it is minimal, it is not under-specified for a simple retrieval operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, full schema coverage, and annotations that cover safety and idempotency, the description is reasonably complete. However, it does not indicate what the tool returns (e.g., the full location object), which could be helpful given there is no output schema. The openWorldHint annotation hints that results may be incomplete, but the description does not explain this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the single optional parameter locationId with a description and default behavior ('Defaults to GHL_LOCATION_ID when omitted'). The tool description adds no additional meaning beyond what the schema provides, 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.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb 'Get' and a resource 'Sub-Account (Formerly Location)' which unambiguously identifies the operation. However, it does not differentiate from sibling tools like locations_search_locations or locations_put_location, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or context that would help an agent choose between this and other location-related tools such as locations_search_locations or locations_get_location_tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context, such as expected return format or error conditions, but does not contradict the annotations either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, a single terse sentence, which is appropriate for a simple retrieval tool. It is not verbose or redundant, but it is also minimal, lacking any additional structure that might aid comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not mention what the response will contain, which could be useful. However, for a simple 'get by ID' operation, the provided information may be sufficient, though it misses opportunities to clarify the returned tag object or distinguish from related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both tagId and locationId having descriptions. The locationId description already notes the default behavior ('Defaults to GHL_LOCATION_ID when omitted'), so the tool description adds no additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('tag by id'), making the tool's purpose evident. It is specific enough to distinguish from list-type siblings like locations_get_location_tags, though it does not explicitly mention the location scoping that is implied by the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention that this is for retrieving a single tag by ID while locations_get_location_tags lists tags, nor does it explain any prerequisites or context for use.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate them. The description adds no additional behavioral details (e.g., return format, pagination). It is consistent with the annotations but adds minimal value beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded and gets to the point immediately. While it is extremely concise, it does not waste any cycles; however, it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 optional filter parameters and pagination, but the description doesn't mention that it supports filtering or that it returns a paginated list. However, the schema covers these details, and the annotations cover safety. The description is minimal but not misleading, so it's adequate but could be more complete for an agent to understand the full capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 7 parameters (skip, limit, userId, endDate, eventId, meterId, startDate) are already well documented in the schema. The description does not add any parameter-related semantics, which is acceptable given the high schema coverage. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all wallet charges' clearly states a specific verb ('Get') and resource ('wallet charges'), and the word 'all' distinguishes it from the sibling tool marketplace_get_specific_charge. However, it doesn't explicitly mention the list/pagination nature or the ability to filter, though that is implied. It's clear but not fully elaborated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that marketplace_get_specific_charge should be used when retrieving a single charge, nor does it hint at filtering or scenarios where this list tool is appropriate. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds a scope clarification ('app subscription and usage plans') but does not disclose any additional behavioral traits such as return format, pagination, or required permissions. Since the bar is lower with annotations, this is acceptable but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the key action ('Get rebilling config') front-loaded. It is concise and free of filler, though it could have included a brief note on the optional locationId default without adding clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read operation with fully documented parameters and safety annotations, the description is minimally sufficient. However, it does not explain what the rebilling config contains or the shape of the response, which could be relevant for an agent expecting to use the result. This is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (appId, locationId) have clear descriptions in the schema. The tool description does not add any further parameter-level meaning or clarify interactions between parameters beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and a specific resource ('rebilling config for an app subscription and usage plans'), which is unambiguous. While it does not explicitly differentiate from sibling marketplace tools like marketplace_get_specific_charge, the resource scope is distinct enough that an agent can infer the intended target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives (e.g., marketplace_get_charges or saas_api_get_saas_plan). It does not mention any prerequisites, conditions, or exclusions, leaving the agent to infer suitability from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds 'File or Folder' to clarify the resource scope, which is mildly useful but does not elaborate on consequences, reversibility, or authorization. It does not contradict annotations, so credit is given for the added 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: 'Delete File or Folder' is a single, front-loaded sentence with zero waste. It immediately communicates the action and target without any padding, which is ideal for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a destructive tool. It does not explain what the 'id' parameter refers to (media content ID) nor does it distinguish this from medias_bulk_delete_media_objects, which is critical for correct selection. It also omits any mention of the permanence or the effect of altId/altType beyond schema descriptions. Given the low complexity and annotations covering safety, more guidance on usage scope is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, with altId and altType having descriptions about location defaults. The description 'Delete File or Folder' does not add any parameter semantics. Since coverage is above 50%, the baseline is 3, and the description does not improve upon it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete File or Folder', specifying the action and resource. It is specific about what is being deleted (media content) but does not differentiate from sibling tools like medias_bulk_delete_media_objects, which also deletes media objects. This is a clear purpose but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives. The description does not mention whether it handles single items, require prerequisites, or when not to use it. The existence of bulk delete siblings without any distinguishing context leaves the agent without clear usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds no additional behavioral context, such as what happens if the config is not found, whether it returns API keys, or any side effects. Since annotations cover the key traits, a neutral score of 3 is appropriate—no contradiction, but no added value either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (four words) with no filler or repetition. It front-loads the action and target. However, it might be so terse that it sacrifices clarity (e.g., what 'given' refers to), but for a simple fetch operation it's appropriately sized without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema. Annotations cover safety. The description is minimal but doesn't clarify what the provider config contains or the shape of the response, which could be useful since there is no output schema. Given the low complexity, this is adequate but not complete—an agent might not know what to expect from the returned config.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%—the single parameter 'locationId' has a description and default behavior. The description itself adds no extra meaning to the parameter beyond what the schema provides. Baseline 3 is correct because the schema already fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch given provider config' states a clear action (fetch) and resource (provider config). It distinguishes from sibling payment tools like payments_list_coupons or payments_create_config by focusing on fetching a specific config. However, the term 'given' is vague and doesn't specify what identifies the config (e.g., provider or location), and it doesn't name any sibling, so it's clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There are many payment tools (payments_list_coupons, payments_get_coupon, payments_create_config, etc.), but the description doesn't explain the scenario for fetching a provider config specifically or mention any exclusions. An agent would have to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds no behavioral detail beyond the action itself, such as pagination behavior, response format, or any side effects. Since annotations carry the main burden, a baseline score of 3 is appropriate—no contradiction, but minimal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short phrase—'List White-label Integration Providers'—with zero waste and the action front-loaded. It is appropriately sized for a straightforward list operation and doesn't include redundant information already present in annotations or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having schema coverage and annotations, the description omits any mention of the response structure or what fields each provider includes. Since there's no output schema, an agent has no hint about the returned data shape, which is critical for using the results. Additionally, it doesn't explain how pagination works beyond the parameter descriptions. The description is too terse for an agent to confidently handle the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter (altId, limit, offset, altType) already explained. The description adds no additional meaning about how parameters should be used or their relationships. Since the schema is comprehensive, the description doesn't need to compensate, giving a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb ('List') and resource ('White-label Integration Providers'), which is unambiguous as a read operation. However, it doesn't differentiate from sibling tools like 'payments_list_coupons' or specify what 'white-label' adds to the context, so it's clear but not uniquely discriminating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'payments_create_integration_provider' or 'payments_create_integration'. The description doesn't mention prerequisites, the purpose of listing providers, or scenarios where it should be preferred. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write. The description adds no extra behavioral context, such as irreversibility, permission requirements, or cascading effects on related data. It simply repeats the destructive action implied by the name and 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the operation with no unnecessary words. It is well-sized for a simple delete operation and delivers the core purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward deletion tool, the description, combined with annotations (destructive, non-read-only) and a fully described schema, covers the essential context. It does not mention return values or side effects, but for a delete operation this is typically implicit, and annotations already signal the destructive nature. Minor gaps like whether deletion is permanent or if locationId defaulting is relevant are handled by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (priceId, productId, locationId) are already documented with descriptions. The tool description adds no additional meaning about parameters, such as format, constraints, or relationships. Since the schema carries the full burden, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), the resource (Price by ID), and the scope (for a Product). It effectively distinguishes this from sibling operations like create, update, list, or get price, though it is terse and adds little beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as products_update_price_by_id_for_product or products_get_price_by_id_for_product. It neither mentions prerequisites nor scenarios where deletion is appropriate, leaving the agent to infer usage entirely from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, which the description aligns with by saying 'delete'. However, the description adds no additional behavioral context such as irreversibility, side effects on related data (e.g., inventory, reviews), or permission requirements. Since the bar is lower with annotations, this adds nothing beyond what is already known.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Delete Product by ID') and front-loaded without any wasted words. It is appropriately sized for a simple delete tool, though it sacrifices nuance. It earns a 4 for being tight and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with three parameters and no output schema, the description is minimally sufficient but lacks context about potential side effects (e.g., deletion of associated prices, reviews, or inventory) or confirmation of what happens after deletion. The openWorldHint=true suggests unknown effects, but the description does not elaborate. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are individually documented. The description itself does not clarify parameter usage beyond the schema; it merely states the operation. With full schema coverage, a baseline of 3 is appropriate as the description adds no meaningful parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Product by ID' clearly identifies the verb (delete), the resource (Product), and the identifier (by ID). It distinguishes this from sibling tools like products_get_product_by_id and products_update_product_by_id, making the purpose unambiguous without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. It does not mention, for example, that this is for a specific product (not a collection or review) or any context about when deletion is appropriate. The description simply restates the action with no usage 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=true and idempotentHint=true, covering the read-only and idempotent behavior. The description adds the specific authentication requirement (agency-level token) and clarifies that a location PIT is not acceptable. This goes beyond the annotations and is valuable for an agent to avoid incorrect usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is appropriately brief. However, it omits critical details about parameters and the return value, making it under-specified. While it is not verbose, the lack of necessary information reduces its effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 required parameters, no output schema, and zero schema description coverage, the description is highly incomplete. It does not explain the meaning of customerId and subscriptionId, does not clarify what locations are returned, and does not distinguish this tool from similar saas_api tools like saas_api_get_saas_locations. An agent would have insufficient guidance to call this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters, but it only mentions 'stripeId' and 'companyId'. The schema actually requires customerId, subscriptionId, and companyId, and 'stripeId' does not appear in the schema. This is misleading and fails to clarify what customerId and subscriptionId represent. The description adds no meaningful semantic for two of the three required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get locations by stripeId with companyId', which clearly indicates a retrieval operation for locations with specific identifiers. It is specific about the resource (locations) and the operation (get). However, it does not differentiate from the sibling tool saas_api_get_saas_locations, and the mention of 'stripeId' is ambiguous because the schema uses customerId and subscriptionId instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the authentication prerequisite: 'requires an agency-level token, not a location PIT'. This gives a clear condition for when the tool can be used and implicitly warns against using it without the proper token. However, it does not mention when not to use this tool relative to other saas_api tools, nor does it reference any alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to repeat those. However, the description adds no additional behavioral context beyond the annotations—such as effects on related data, irreversibility, or any cascading actions. Given that annotations cover the core safety profile, the description is adequate but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—three words—which is efficient and avoids verbosity. However, it is so minimal that it borders on tautology, essentially restating the tool name. It lacks any structuring or additional context that would aid an agent, but it does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, 2 required, no output schema) and the annotations covering destructive/idempotent behavior, the description is minimally sufficient. However, ambiguity with sibling deletion tools (e.g., delete_post vs. delete_csv vs. this tool) is not resolved, and no guidance on what constitutes a CSV post is provided. An agent might call the wrong deletion tool without clearer context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (csvId, postId, locationId), including a default for locationId. Since schema description coverage is 100%, the schema fully documents the parameters. The description contributes nothing beyond that, so it meets the baseline but adds no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Delete) and a specific resource (CSV Post), which provides clear intent. However, it does not differentiate this from sibling tools like social_media_posting_delete_post (which likely deletes a regular post) or social_media_posting_delete_csv (which deletes a CSV file). The name and description are nearly identical, so an agent might confuse which resource is being deleted without additional context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus other deletion tools (e.g., delete_post, delete_csv, bulk_delete_social_planner_posts). There is no mention of prerequisites, when CSV posts are applicable, or any conditions that select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds no behavioral context beyond the action itself, such as default behavior for locationId (though that is in the schema) or any side effects. Since annotations cover the main safety aspects, the lack of additional transparency is a minor gap, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It is appropriately sized for a simple getter operation and front-loads the essential action. No unnecessary details are included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with two parameters and annotations covering read-only safety, the description is adequate. The schema fully documents parameters, and the tool name implies the return value (tags). However, there is no mention of error handling or output format, which might be expected for a getter, but given the simplicity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both parameters: tagIds is an array of tag IDs, and locationId defaults to GHL_LOCATION_ID when omitted. The description adds no additional semantics beyond what the schema already documents. With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get tags by ids.' It is specific enough to distinguish from siblings like social_media_posting_get_tags_location_id, which retrieves tags for a location, while this fetches by explicit IDs. However, it does not elaborate on the scope of 'tags' (e.g., social media posting tags), though the tool name provides that context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to use this tool versus alternatives. While the name suggests it is for retrieving tags by IDs, the description does not mention prerequisites, exclusions, or when to prefer this over sibling tools like get_tags_location_id. An agent would have to infer usage from the schema and name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what the annotations already provide. Annotations indicate destructiveHint=true and idempotentHint=true, but the description does not elaborate on the consequences of deletion, such as whether associated rates are removed or if the action is irreversible. It simply states the 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, clear sentence without any fluff. It is appropriately sized for a straightforward delete operation and front-loads the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and does not provide context about the operation's effects, such as whether it deletes associated shipping rates or how it interacts with the location context. While the schema covers the parameters, the description does not explain the operational impact or success criteria. For a destructive action, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers all parameters (100%), so the baseline is 3. The description does not add any extra clarity about parameters; it merely names the tool. The parameter descriptions in the schema already explain altId and altType, though the shippingZoneId description is oddly worded as 'ID of the item that needs to be returned' which is a bit off for deletion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (shipping zone), which is specific and distinguishes it from sibling tools like store_delete_shipping_carrier or store_delete_shipping_rate. It is unambiguous and to the point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, conditions, or scenarios where this tool is appropriate. The agent must infer that it is for deleting shipping zones from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint: true, idempotentHint: true, and destructiveHint: false, covering the safety profile. The description adds no extra behavioral context (e.g., error behavior, return format, or auth requirements). It is consistent with annotations and contributes no additional value, warranting a baseline score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, a single phrase with no redundant words. It is appropriately short for a simple get operation, though it lacks any explanatory structure beyond the core statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and that schema covers all parameters and annotations cover safety, the description is minimally sufficient. However, it does not mention that it retrieves a single carrier by ID (though inferred from the required parameter), nor does it indicate the return value shape (no output schema). The lack of distinction from the listing tool leaves some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, with descriptions for altId, altType, and shippingCarrierId. The tool description does not add any additional meaning or clarify parameter relationships, so it meets the baseline for schema-documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Shipping Carrier' provides a clear verb and resource, indicating retrieval of a shipping carrier. However, it is terse and does not clarify that it is by ID or distinguish from the sibling 'store_list_shipping_carriers'. The name uses plural 'carriers' while the description is singular, causing slight ambiguity, but overall the purpose is understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as store_list_shipping_carriers or store_get_shipping_rates. There are no prerequisites, exclusions, or contextual hints given in the description, leaving the agent to infer usage from the schema alone.
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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already convey the safe, read-only nature of the operation. The description adds no behavioral context beyond stating it gets settings, and does not mention behavior like defaults or side effects. Given the strong annotation coverage, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant content. It is appropriately brief for a simple read operation, though it leaves out supplementary details that could aid usage. The structure is clean and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional params, no output schema, and a clear read intent, the description is minimally sufficient. However, it does not explain what 'Store Settings' encompasses or indicate that altId/altType default to GHL_LOCATION_ID (though the schema covers this). The lack of return-value description is acceptable given the absence of an output schema, but the description could be more helpful in clarifying scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both altId and altType are described), so the schema already documents the parameters including defaults and enum values. The description adds no additional meaning beyond what the schema provides, placing it at the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Store Settings' clearly states the action (Get) and resource (Store Settings), distinguishing it from sibling tools like store_create_store_setting. It is specific enough to infer it retrieves store configuration details, though it does not elaborate on what those settings include.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as store_list_shipping_carriers or store_create_store_setting. There is no mention of use cases, prerequisites, or exclusions, leaving the agent to infer applicability solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat these. It adds no extra behavioral context beyond what annotations provide, such as defaulting locationId to GHL_LOCATION_ID (which is in the schema) or any side effects. Since annotations carry the safety profile and there is no contradiction, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with zero filler. It is front-loaded and to the point. There is no wasted wording, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple read operation with one optional parameter and strong annotations, the description is minimally adequate. However, it does not indicate what the integration object contains (no output schema), nor does it mention if a prior creation is required. For a tool in a larger ad manager suite where integration status matters, a bit more context (e.g., 'Retrieves the Facebook integration configuration for the location') would improve completeness, but it is not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter locationId with a description ('Location identifier Defaults to GHL_LOCATION_ID when omitted.'), giving 100% coverage. The tool description adds no additional meaning on top of the schema. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Facebook integration' clearly states a retrieval action on a specific resource (Facebook integration), and the name disambiguates from Google or LinkedIn counterparts. However, it does not specify what aspects of the integration are returned or how it differs from a list or details variant, though no such sibling exists for Facebook. It is essentially a restatement of the name, but sufficient for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., having an integration created), conditions under which this should be called, or contrast with siblings like ad_manager_fb_create_integration or ad_manager_google_get_integration. An agent would have to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing this as a safe read operation. The description contributes no additional behavioral context beyond 'Get', which is consistent. No contradictions exist, but the description adds little value beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It is appropriately minimal for a simple get-by-id tool, and the content is front-loaded and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, complete parameter schema, and annotations covering safety, the description is minimally sufficient. It does not explain the distinction between custom and data segments, but the enum values are self-explanatory. It also doesn't mention the need for a Google Ads integration or what the response contains, but no output schema is provided. The description is adequate but could be slightly more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all three parameters described, including the enum for 'type' and the default for 'locationId'. The description adds no additional meaning beyond the schema, so it relies entirely on the schema for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get segment by ID' clearly specifies the action (get), resource (segment), and method (by ID). This distinguishes it from listing tools like ad_manager_google_get_segments, though it doesn't elaborate on what a segment is in this context. The purpose is unambiguous and aligns with the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that 'type' is required to differentiate custom vs. data segments, nor does it say to use this for retrieving a single segment rather than listing all. The agent must infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond what annotations provide, such as authentication requirements or what data is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the tool's purpose. Every word earns its place; there is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no output schema, the description is adequate but doesn't explain what the returned user object contains or any context about the LinkedIn advertising context. It's minimal but functional, leaving room for improvement in clarifying the return value or usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter 'locationId' has a description explaining its default. The tool description adds no parameter-specific context, so it relies on the schema. 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get') and resource ('current LinkedIn user'), making it clear what the tool does. While it doesn't explicitly differentiate from sibling tools, the 'LinkedIn' qualifier and the tool name disambiguate it from Facebook and Google equivalents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like ad_manager_fb_get_current_user or ad_manager_google_get_current_user. The platform is implied by the description, but no explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description's 'Remove' aligns without contradiction. However, the description adds no extra behavioral context, such as permanence, impact on related data, or error handling. Since annotations cover the destructive nature, the description does not need to restate it, but it also fails to provide any new details beyond what the structured metadata already conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundancy. It is front-loaded with the core action and resource, which is appropriately concise for such a simple operation. However, it could have included a brief note about the required IDs without losing conciseness, but as it stands, it is neither verbose nor under-specified to a fault.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward delete operation, the description is reasonably complete, especially given that annotations cover destructive behavior and idempotency. However, it does not mention return values (though there's no output schema anyway) or any side effects like permanent removal or cascading effects. The lack of detail about agentId's meaning and the absence of an output schema leave some ambiguity, but it's acceptable for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% — only actionId has a description, while agentId has none. The description does not compensate for this gap; it merely states the action without clarifying what agentId refers to or how it relates to the action. Given the medium coverage, the description should have added meaning for the undocumented parameter, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove Action from Agent' clearly states a specific verb ('Remove') and a precise resource ('Action from Agent'), making the tool's purpose unmistakable. It naturally distinguishes itself from sibling tools like conversation_ai_create_action (create) and conversation_ai_update_action (update), and even from conversation_ai_delete_agent (which deletes the agent itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, such as prerequisites (e.g., the action must exist) or when to choose a different operation (e.g., update instead of delete). While the verb and resource imply usage, there's no mention of exclusions or conditions, leaving the agent to infer context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds only that it is for the 'latest operation' but does not disclose error behavior, response format, or what happens when no operation exists. With annotations covering safety, the description's marginal behavioral context is minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence with no redundant phrasing. It directly states the action and target, achieving maximum conciseness without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does not explain what the crawling status will look like or what values are possible. It also leaves 'latest operation' ambiguous—does it require the operationId of the latest operation or does it infer it? For a read-only getter, this minimalism is acceptable but lacks important detail about the expected response and semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning each parameter (operationId, knowledgeBaseId, locationId) is already described in the schema. The description does not add any clarification about parameter relationships or how 'latest' relates to the provided operationId, so it provides no extra semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and a resource ('crawling status'), and it is distinct from the sibling knowledge_base_get_knowledge_base_by_id tool, which retrieves the knowledge base itself. However, 'latest operation' is somewhat vague and does not explicitly clarify that it refers to the most recent crawl operation for the given knowledge base, leaving room for interpretation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. There is no explicit 'use this when...' or 'for X, use Y instead' wording, leaving the agent to infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint=false, destructiveHint=false) and non-idempotent. The description adds the authentication requirement, which is useful context beyond annotations. It does not describe side effects, return values, or any other behavioral details, but given the annotations cover the basic nature, the addition is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that front-loads the core action ('Create Sub-Account') and then immediately gives the critical usage constraint (token requirement). It is concise and free of fluff, earning a high score for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, nested objects, no output schema), the description is minimal. It does not explain what a sub-account/location is, when to use it in a typical workflow, or what the response will be. Without a clear conceptual context, an agent may struggle to correctly use this tool despite the rich schema. This is a significant gap for such a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 94% of the 16 parameters with descriptive text for each, so the schema already provides solid parameter semantics. The tool description itself adds no parameter-specific information. The baseline score of 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Create') on a specific resource ('Sub-Account') and notes its former name ('Location'). It is distinct from sibling tools by name and the verb-resource pairing is explicit. However, it does not elaborate on what a sub-account/location represents in the domain, leaving some ambiguity for agents unfamiliar with the context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an important prerequisite by stating it requires an agency-level token and not a location PIT. This helps an agent determine when the tool is applicable. However, it does not mention any alternatives or when not to use this tool, so guidance on choosing between this and similar creation tools is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate it is not read-only and not destructive, so the description carries the burden of explaining side effects. It discloses the token requirement but omits what happens to the locations (e.g., billing impact, reversibility, partial failures). This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence, front-loaded with the action and scope. The token requirement is appended as crucial context. There is no wasted language, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk mutation with no output schema and minimal parameter documentation, the description is incomplete. It lacks information on return behavior, error handling, whether the operation is atomic, and any prerequisites beyond the token. An agent cannot fully predict the consequences of calling this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only locationIds has a minimal description; companyId has none). The description adds no parameter information beyond the schema, failing to compensate for the undocumented companyId or clarify the exact format of locationIds. The agent must infer meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Disable SaaS) and the scope (for locations), distinguishing it from sibling tools like bulk_enable_saas. It also adds a critical authentication prerequisite, 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a key usage constraint (requires agency-level token, not a location PIT), which helps the agent know when it can be called. However, it does not explicitly contrast with alternatives like single-location disable or enable tools, leaving some ambiguity about when to choose this over similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), non-idempotent, and non-destructive, which the description aligns with. The addition of the token requirement is valuable context beyond the annotations. However, it does not elaborate on the effects of disabling SaaS (e.g., whether subscriptions are paused), which would 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the action, target, and a critical requirement. It is free of fluff and front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The essential calling information is present: action, params, and authentication requirement. However, it lacks a deprecation notice and any indication of side effects or return behavior. Given the existence of a non-deprecated counterpart, this incomplete context could lead an agent to use an outdated tool without knowing it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for both parameters (companyId and locationIds) with 100% coverage, so the schema already explains their meaning. The description adds no additional parameter-level detail, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Disable SaaS for locations'. It is specific and unambiguous. However, it does not distinguish this tool from the non-deprecated sibling saas_api_bulk_disable_saas, which is a missed differentiation opportunity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a necessary authentication requirement (agency-level token) but provides no guidance on when to use this tool versus alternatives. There is no mention of deprecation or suggestion to use the newer saas_api_bulk_disable_saas, leaving the agent without direction on tool 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?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the authentication constraint (agency-level token vs location PIT), which is a behavioral trait not covered by the schema or annotations. However, it does not describe pagination behavior, return format, or other potential side effects. It adds moderate value beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that states the purpose and an important constraint upfront. Every word adds value, with no filler or redundancy. It is well-structured and immediately communicates the core operation and a critical prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated tool, the description omits guidance to use the non-deprecated alternative (saas_api_get_saas_locations). While the name clearly indicates deprecation, a complete description would explicitly advise against new usage or point to the replacement. It also does not clarify what 'SaaS Locations' returns beyond the name, though the schema covers parameters. It is adequate but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (page and companyId) with descriptions already present. The tool description does not add any additional meaning or nuance about these parameters. Since the schema fully documents them, the baseline of 3 is appropriate; no extra clarity is contributed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Get SaaS Locations'. It is specific and unambiguous about what the tool does. However, it does not explicitly distinguish itself from the sibling 'saas_api_get_saas_locations' (non-deprecated), relying on the name to convey that it is the deprecated version. A clear purpose, but missing sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (requires an agency-level token, not a location PIT) but does not provide any guidance on when to use this tool versus alternatives like saas_api_get_saas_locations or saas_api_locations. It doesn't advise preferring the non-deprecated version or explain trade-offs. No explicit when-to-use or when-not-to-use guidance is given.
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 annotations already declare non-read-only and non-destructive behaviors. The description adds the crucial auth context (agency-level token, not a location PIT), which is not in the annotations. However, it does not disclose side effects or reversibility, so it only partially augments the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action and places the key requirement in a parenthetical. No unnecessary words; every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action and auth requirement, and the schema handles parameter documentation. Missing are explicit guidance on sibling selection and expected outcome, which makes it adequate but not 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage, so all parameters are documented. The tool description adds no parameter-level details, relying entirely on the schema. This meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action (pause) and resource (location), making the purpose unambiguous. However, it does not differentiate from sibling tools like saas_api_enable_saas_location or the deprecated saas_api_pause_location_deprecated, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an authentication requirement (agency-level token) but gives no guidance on when to use this tool versus alternatives, such as the enable or deprecated pause tools. There are no explicit exclusions or scenario-based recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds a meaningful behavioral detail: the auth scope requirement (agency-level token vs location PIT), which is not covered by annotations. However, it does not describe the return format, pagination behavior, or how filtering works, which would add further transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, extremely concise, which is good for front-loading the action. However, it lacks any structured breakdown of parameters or usage context, and the sentence is somewhat sparse given the tool's complexity. It is not verbose, but it could benefit from a more structured format without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 required parameters, no output schema, and minimal schema descriptions, the description is far from complete. It covers the date range and auth requirement but leaves out parameter meanings, any examples, pagination details, or response expectations. For a tool with this complexity, the description is inadequate for an agent to call it correctly without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only lastDoc has a description). The description infers that 'from' and 'to' are date boundaries, but it does not explain snapshotId, companyId, limit, or lastDoc beyond the schema. It does not compensate for the low coverage, leaving most parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('Snapshot Push') with an explicit scope ('between Dates'). It clearly differentiates from sibling snapshots_get_latest_snapshot_push, which retrieves only the latest, and the name aligns with the action. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (agency-level token, not a location PIT) which is useful context, but it does not explicitly state when to choose this tool over its siblings (e.g., 'use this when you need a date range rather than just the latest'). The guidance is implied by the name and description but not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. It adds a small amount of context by indicating the filter (location id), but does not disclose behavior such as pagination (given skip/limit params) or the return format. Since annotations cover the safety profile, 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence that directly states the core purpose. No fluff or redundant information. It is front-loaded with the action and resource. Appropriate for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with optional parameters and no output schema. The description is adequate but lacks details about the response (e.g., that it returns a paginated list, given skip/limit) and what 'categories' refers to. While annotations cover safety, an agent might benefit from knowing that skip/limit are for pagination. This is a minor gap, so 3 is suitable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (skip, limit, locationId, searchText) are already described in the schema. The description adds no additional meaning beyond indicating the primary filter (location id). With high schema coverage, the baseline is 3 and the description doesn't enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('get') and resource ('categories') with a specific filter ('by location id'). It clearly distinguishes from the sibling social_media_posting_get_categories_id by the parameter. However, it doesn't specify what kind of categories (e.g., social media categories) or elaborate on the response, so it's clear but not fully specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only states the action without context on selection criteria, exclusions, or why one would choose this over the id-based variant. There is no mention of prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe, non-mutating operation. The description adds no additional behavioral context (e.g., return format, potential empty results, or authentication needs) but does not contradict the annotations. Given the annotations carry the safety profile, the sparse description is not misleading, though it misses an opportunity to add value beyond the structured 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence: 'Get Instagram Professional Accounts'. It is extremely concise, with zero fluff or redundancy. All words carry meaning, and it is front-loaded with the core action and target. This is an exemplary level of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read operation with two parameters (one required) and no output schema. The description is minimal but adequate for a basic getter; however, it omits what the response will contain (e.g., a list vs. single object) and does not mention any filters or scoping beyond the required parameters. Given the lack of an output schema, a bit more detail about the return value would improve completeness, but the tool is simple enough that the current description does not leave the agent completely in the dark.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (accountId and locationId) with clear descriptions. The tool description adds no parameter-specific meaning, which is acceptable given the schema is already comprehensive. The baseline of 3 applies because the schema does the heavy lifting, and the description does not need to reiterate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Instagram Professional Accounts' clearly states the verb (get) and resource (Instagram professional accounts), making the core purpose unambiguous. However, it does not specify whether it fetches a single account or a list, nor does it clarify the relationship to the 'page group' in the tool name, which could cause minor ambiguity. It is still distinct from sibling tools like 'get_facebook_page_group' due to the explicit Instagram reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternative social media retrieval tools (e.g., social_media_posting_get_facebook_page_group or social_media_posting_get_linkedin_page_profile). It does not mention prerequisites, context, or exclusions. The agent is left to infer usage from the tool name alone, offering no strategic direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is well-covered. However, the description adds no extra behavioral context beyond the act of fetching. It does not describe what data is returned, potential failure modes (e.g., missing account), or any side effects, but given the annotations, this is acceptable for a read operation. No contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just one short sentence with no fluff. It is perfectly concise and the intent is front-loaded. Every word carries meaning, making it an example of efficient writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, both documented) and annotations that cover safety, the description is minimally sufficient. However, it lacks context about what 'profile' entails, whether an account must be pre-attached, and what the response will look like. In a landscape of many similar 'get_*_profile' tools, the description alone doesn't fully equip an agent to decide when to call it, though the sibling names help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — both parameters have descriptions (accountId and locationId). The tool description itself adds no parameter details, but the baseline of 3 is appropriate because the schema already carries the semantic burden. The description does not clarify the purpose of locationId (e.g., that it defaults to GHL_LOCATION_ID), but the schema already states that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get Twitter profile' uses a specific verb (Get) and a clear resource (Twitter profile). It is unambiguous about what it does, but it does not distinguish itself from sibling tools like social_media_posting_get_facebook_page_group or social_media_posting_get_tiktok_profile. The name and description are essentially redundant, but it is still clear and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling 'get_*_profile' tools for different platforms, there is no indication of the conditions that would lead an agent to choose this one. It does not mention prerequisites such as needing an attached Twitter account, nor does it note that other tools exist for other platforms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, idempotentHint=true, and openWorldHint=true, which cover the safety and idempotency profile. The description adds no extra behavioral context beyond stating the action. It does not explain what 'starting OAuth' entails (e.g., returning a redirect URL, initiating a consent flow), so beyond the annotations, there is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the action. No filler, no repetition, and it is appropriately sized for such a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an OAuth starter tool with no output schema and annotations covering safety, the description provides the basic purpose. However, it does not explain critical nuances like what the result of 'starting' is, what 'reconnect' means, or when to pass a 'locationId'. While the schema documents parameters, the descriptions of parameters are vague (e.g., 'Page', 'Reconnect'), so the tool is not fully self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters, so the schema already documents each parameter. The description does not add any semantic detail or clarify parameter usage (e.g., what 'reconnect' or 'page' mean in context). Baseline of 3 is appropriate because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Starts' and the resource 'OAuth For Google Account', which is specific and distinguishes this tool from sibling OAuth tools for Facebook, Instagram, LinkedIn, etc. It is not a tautology and conveys exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the other social_media_posting_start_*_oauth siblings. It does not mention prerequisites, conditions, or alternatives, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context (e.g., what details are returned, authentication requirements, or rate limits). It does not contradict annotations, so a score of 3 is appropriate for neutral but insufficient extra disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. Every word contributes to stating the core function. It is ideally front-loaded and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 required parameter and no output schema, the description is adequate. It tells the agent the essential purpose. However, it could be slightly more complete by explicitly noting it is for a single Facebook ad account and contrasting with the plural list variant, but the name and schema largely compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters: locationId ('Location identifier Defaults to GHL_LOCATION_ID when omitted.') and adAccountId ('Ad account identifier'). The tool description adds no additional meaning beyond the schema, so the baseline of 3 holds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get ad account details' clearly states a specific verb (get) and resource (ad account details). It is unambiguous about what the tool does. However, it does not explicitly differentiate from siblings like ad_manager_fb_get_ad_accounts (plural) or platform-specific variants (google, li), though the name includes 'fb' and 'ad account' singular, which helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus related tools such as ad_manager_fb_get_ad_accounts, ad_manager_google_get_ad_account_details, or ad_manager_li_get_ad_account_details. There is no mention of selection criteria, prerequisites, or alternatives. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Create', which is consistent with readOnlyHint=false and matches the annotations. It does not add any behavioral information beyond the annotations, such as whether the operation is idempotent (annotations say false) or any effects on existing integrations. No contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, immediately clear and free of any unnecessary words. It is appropriately front-loaded and minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is insufficient for an agent to understand what a LinkedIn integration is, what the creation entails, or what the result will be. It does not explain any preconditions, how it relates to other LinkedIn ad manager tools, or what a successful creation achieves.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are described in the schema (100% coverage), so the schema already conveys their meaning. The description adds no additional semantics, relationships, or formatting details beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Create' and the resource 'LinkedIn integration', clearly distinguishing it from the Facebook and Google integration tools by naming the platform. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the Facebook or Google integration creation tools, nor any prerequisites or context for when a LinkedIn integration is needed. The description offers no exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already cover safety and idempotency. The description adds no behavioral detail beyond the bare action, so it does not improve transparency. It's acceptable but not additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is front-loaded and directly states the purpose, which is appropriately minimal for a straightforward list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one optional parameter and no output schema, the description is nearly sufficient. It could benefit from stating that it lists all ad accounts for the given location, but the name and parameter make this reasonably clear. Misses only optional context like pagination or return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the single parameter locationId including its default behavior. The description itself contributes no parameter meaning, so it stays at the baseline for 100% schema coverage. The default information is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get LinkedIn ad accounts' clearly states the verb and resource. It implicitly distinguishes from Facebook and Google siblings by naming the platform. However, it doesn't specify the scope or filtering behavior, leaving some ambiguity about whether it returns all accounts or ones tied to a location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like ad_manager_li_get_ad_account_details. The description gives no context about which scenarios warrant listing all accounts versus fetching a specific one, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true and idempotentHint=true, which the description does not contradict. However, the description adds no behavioral context beyond the basic delete action—no mention of permanence, side effects on related data, or whether deletion fails for referenced fields. With annotations covering the safety profile, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single five-word phrase with zero redundancy. It is extremely concise and front-loads the core action, making it easy to scan. Every word carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one required id parameter and no output schema, the description is minimally viable. It doesn't mention return values, error conditions, or the effect on dependent entities, but the destructive and idempotent annotations mitigate the safety gap. Still, it lacks any contextual detail that would help an agent ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the tool description provides only 'By Id', which merely echoes the parameter name. It does not clarify the format, origin, or any constraints (e.g., that it must be an existing custom field id). The description fails to compensate for the schema's lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete Custom Field By Id' clearly states the action (delete), the resource (custom field), and the identifier used. It distinguishes from sibling tools like custom_fields_delete_custom_field_folder and other custom field operations (create, update, get). The purpose is unambiguous and immediately actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context about prerequisites, and no mention of related tools that might be more appropriate. There is no indication of when deletion is appropriate or what to consider before calling it. An agent is left to infer usage solely from the operation name.
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 annotations already signal destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. However, the description does not add any extra behavioral context such as irreversibility, potential cascade effects, or prerequisite existence of the FAQ. Since the annotations carry the burden, the description adds little beyond restating the action, keeping this at a neutral score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose without any fluff. It is efficient and communicates the essential action clearly. It could arguably be slightly longer to include usage guidance, but that is a content concern, not a structural one; the structure is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and annotations covering destructiveness, the description is mostly complete. However, it does not explicitly differentiate from the related knowledge_base_delete_knowledge_base sibling, which could lead to misuse. The schema clarifies the ID is a FAQ ID, but the description could mention that it deletes only the FAQ, not the whole knowledge base, to prevent errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the single parameter 'id' with description 'faq ID as string'. The description does not add any additional meaning about where to obtain this ID or its format. Given the full schema coverage, no compensation is required, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Delete') on a specific resource ('existing knowledge base FAQ'), which distinguishes it from sibling tool knowledge_base_delete_knowledge_base that would delete the entire knowledge base. The verb-resource pairing is explicit and unambiguous, so an agent can infer this targets a FAQ entry within a knowledge base.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not explicitly mention that deletion of the entire knowledge base should use knowledge_base_delete_knowledge_base, nor does it list any preconditions or exclusions. Given the generic tool name 'knowledge_base_delete', an agent might confuse it with deleting the whole knowledge base, and the description does not clarify this distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully disclose the safe, non-mutating, idempotent behavior. The description adds no additional context beyond 'Get', such as error behavior, return format, or authentication requirements. Since annotations carry the burden and the description is consistent but minimal, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the action and resource, and every word contributes to the meaning. This is an exemplar of brevity and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id operation with one required parameter and no output schema, the description is adequate but not complete. It does not mention what is returned (e.g., the full knowledge base object) or any behavior like null for missing IDs. Given the low complexity, this is a minor gap, but the lack of explicit return information limits completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It adds only the implication that knowledgeBaseId is the identifier used for retrieval, which is already evident from the parameter name and the tool name. It does not explain the format, requiredness (though schema lists it), or any value constraints. This is insufficient given the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get knowledge base by ID' clearly specifies the verb (get), the resource (knowledge base), and the identifier (by ID). This is specific and distinguishes it from sibling tools like knowledge_base_list, knowledge_base_create, and knowledge_base_delete. It is not a tautology and provides a clear, unambiguous action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or comparisons to other knowledge base tools or other get-by-id tools. An agent is left to infer usage from the name alone, which is insufficient given the large sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, so the description carries some burden to explain mutation behavior. It adds one meaningful behavioral note: the auth token requirement. However, it does not describe side effects, reversibility, or what happens on success. This is a partial disclosure beyond annotations, meeting a baseline but lacking depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and then states the key requirement. It avoids any wasted words and is easily scanned by an agent. This is an exemplar of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 12 parameters, 2 required, and no output schema, the description is very minimal. It does not explain the purpose of the tool beyond 'enable SaaS' nor the context of the auth requirement. It omits any mention of deprecation or alternative tools, and provides no guidance on the expected outcome. Given the complexity, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 92%, so the schema already documents most parameters. The description adds no extra parameter semantics, such as explaining the relationship between required parameters (companyId, isSaaSV2) or the optional ones. Since the schema already handles parameter documentation, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Enable SaaS for Sub-Account'. It also clarifies terminology with '(Formerly Location)', which adds precision. However, it does not explicitly differentiate itself from the sibling tool 'saas_api_enable_saas_location' (the non-deprecated version), though the name hints at deprecation. This is a clear purpose but lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical usage constraint: 'requires an agency-level token, not a location PIT'. This tells the agent when this tool can be used. However, it does not mention that this is the deprecated version or point to the non-deprecated alternative, nor does it describe any exclusions or conditions beyond the token type. This is useful but incomplete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the bar for additional disclosure is lower. The description adds the token requirement, which is useful context not present in annotations. It does not elaborate on response format, pagination, or errors, but these are less critical given the explicit safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main action and includes the essential token constraint. It avoids redundancy and is efficiently structured, though it could be slightly expanded with sibling differentiation without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with one parameter and no output schema, the description covers the purpose and a critical prerequisite. It lacks details on the returned data or any edge cases, but given the tool's simplicity and the safety annotations, it is minimally adequate without being comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter `companyId` with 'Company ID to get agency plans for', so the description adds no extra semantic value. Per the rubric, with high schema coverage the baseline is 3; the description does not go beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Agency Plans, which is a specific verb and resource. It also adds a key qualifier about the required token type, helping distinguish it from sibling tools. However, it does not explicitly contrast itself with the non-deprecated sibling `saas_api_get_agency_plans`, so it falls short of a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a usage prerequisite—requires an agency-level token, not a location PIT—which serves as a guideline for when this tool is appropriate. It does not, however, mention when to avoid it or point to the alternative non-deprecated tool, leaving part of the decision implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds the token authorization requirement, which is a useful behavioral detail not in annotations. However, it does not disclose potential side effects, return behavior, or other consequences beyond that, so it only partially augments 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. It front-loads the core action and includes a critical prerequisite parenthetically. No fluff, every word earns its place, though it could be slightly more structured (e.g., separate sentence for the token requirement) without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 11 parameters, 9 required, nested objects, and no output schema. The description is extremely minimal—it provides the action and a token requirement but omits context about what the custom menu link is, how the parameters interrelate (e.g., showOnCompany vs. showOnLocation), or what a successful response looks like. For a tool of this complexity, more contextual guidance is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%–all parameters have descriptions in the schema. The tool description adds no additional meaning for parameters (e.g., no explanation of conditional dependencies like showToAllLocations vs. locations). With full schema coverage, a score of 3 is baseline for not detracting, but it does not elevate the guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create Custom Menu Link') and the resource (custom menu link), distinguishing it from sibling tools like get, update, and delete. The added note about requiring an agency-level token makes the purpose even more specific and useful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a key usage prerequisite (agency-level token vs. location PIT) which is helpful, but it does not explicitly mention when to use this tool compared to its siblings (e.g., 'use this to create, use update_custom_menu to modify'). The creation intent is implicit but not contrasted with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the token requirement, which is genuinely useful and not available in any structured field. However, it does not disclose what the response contains (e.g., the full menu object) or any error behavior, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that states the action first then the key requirement. No filler or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 strong annotations, the description is adequate but has gaps: it doesn't explicitly say what the return value is (the menu object vs. just a link), nor does it mention the possibility of a not-found response. The token requirement is covered, but the ambiguity around 'Link' affects completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter, customMenuId, is already described as 'Unique identifier of the custom menu'. The description adds no additional meaning or context about the parameter, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get Custom Menu Link' with a clear verb and resource, but the phrase 'Link' is ambiguous—it could mean retrieving a link or the full menu object. The tool name clearly indicates fetching by ID, but the description doesn't reinforce the by-ID semantics or differentiate from the sibling get_custom_menus (plural), which lists all menus. Still, the purpose is understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a specific prerequisite: requires an agency-level token, not a location PIT. This is useful context but does not guide when to choose this tool over the sibling custom_menus_get_custom_menus or when to avoid it. No alternatives or exclusions are mentioned, so the agent must infer that IDs are needed for this call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds nothing beyond the purpose; it does not mention return behavior, potential outcomes (e.g., what happens when funds are insufficient), or any side effects. It is consistent with the annotations, so no contradiction, but it adds minimal value beyond 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that leads with the verb and states the exact condition. It contains zero filler and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, no output schema, read-only annotations), the description is nearly complete. However, it does not specify which account is being referenced (e.g., the authenticated location's marketplace account) or clarify the concept of 'sufficient funds' beyond the literal meaning. These are minor ambiguities that could affect correct interpretation in some contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. There is nothing for the description to elaborate on regarding parameters. Per the rubric, a baseline of 4 applies to tools with no parameters, and the description does not need to compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Check') and resource ('account') and specifies the condition ('sufficient funds'). It is specific enough to distinguish from other marketplace tools like marketplace_charge or marketplace_get_charges, though it does not explicitly name a sibling that might be confused with it. The name and description align well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context about the account being checked, and no mention of prerequisites or typical use cases. It only states the action itself, leaving the agent to infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations clearly mark the tool as readOnlyHint, idempotentHint, and destructiveHint:false, so the agent knows it is a safe read operation. The description adds no further behavioral context such as pagination semantics or response format, but the schema already covers pagination via limit/offset. With annotations covering the safety profile, this is acceptable but not enhanced by the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is direct and front-loaded, stating the action and resource immediately. This is an appropriate level of conciseness for a simple listing operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should hint at what is returned. 'List Prices' implies an array of prices, but it does not describe the response structure, pagination behavior, or any special considerations. Given the simplicity and the annotations that establish the operation as read-only, the description is minimally adequate but could be more informative about the result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters documented. The tool description does not add extra meaning beyond the schema, but since the schema is complete, the baseline of 3 is appropriate. Parameters like productId, limit, and offset are fully described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Prices for a Product' states a specific verb (List) and resource (Prices for a Product), clearly distinguishing it from sibling tools like products_get_price_by_id_for_product (which fetches a single price) and products_create_price_for_product. An agent can infer the tool's function from the name and description without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as products_get_price_by_id_for_product or products_create_price_for_product. It does not mention any conditions, exclusions, or alternative selections, leaving the agent to infer usage purely from the name and schema.
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, and destructiveHint. The description adds the critical constraint that an agency-level token is required (not a location PIT), which is beyond the annotations. However, it omits the deprecation status, which is a behavioral trait (it will likely be removed) not covered by 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with zero fluff, front-loads the purpose and then the auth requirement. Extremely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with annotations covering safety, the description is mostly complete, but it fails to mention that the tool is deprecated (despite the name) and that a non-deprecated alternative exists. This is important context for an agent to make routing decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage of both parameters. The description adds no additional parameter information beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'Location Subscription Details', and adds a specific authentication nuance. However, it does not explicitly differentiate from the non-deprecated sibling saas_api_get_location_subscription, which limits its ability to distinguish between them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a prerequisite (agency-level token) but does not give any guidance on when to use this tool vs alternatives, particularly the non-deprecated version. No exclusions or usage context beyond the auth note.
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=false, covering the safety profile. The description adds value beyond annotations by disclosing an authentication/token requirement (agency-level token), which is not present in the structured data. This is useful for the agent to judge whether it can call the tool. The description doesn't contradict any annotation and reinforces the read-only nature with 'Get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with the primary purpose ('Get SaaS Plan') front-loaded, followed by a key constraint in parentheses. There is no filler or redundant wording. It is well-structured for quick parsing by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two well-documented parameters and annotations covering safety, the description is largely sufficient. However, it omits any reference to its deprecated status or the recommended alternative (saas_api_get_saas_plan), which is a meaningful gap for an agent operating in a large toolset. The token requirement is mentioned, but the deprecation context is missing from the description itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'planId' and 'companyId' having descriptions in the schema itself. The description adds no additional parameter-level information (e.g., formats, defaults, or relationships). Since the schema already documents the parameters, the description meets the baseline for high coverage but provides no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get SaaS Plan' clearly states a verb and resource, making the tool's purpose immediately understandable. However, it does not differentiate from the sibling tool 'saas_api_get_saas_plan' (the non-deprecated version) beyond the name, so the description alone doesn't clarify which one to use. The token requirement adds specificity but is more of a prerequisite than a differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('requires an agency-level token, not a location PIT') but gives no explicit guidance on when to use this tool versus alternatives. Notably, it does not mention that this is a deprecated version and that 'saas_api_get_saas_plan' should likely be preferred. An agent is left to infer that the token type determines appropriateness, which is weak guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the authentication context (agency-level token) and clarifies that a location PIT is inappropriate. This extends beyond the annotations and does not contradict 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that communicates the essential purpose and hard requirement. No unnecessary words or repetition; the description is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deprecated read-only tool with robust annotations and schema, the description is adequate but incomplete. It omits a pointer to the non-deprecated replacement (e.g., saas_api_locations), which would be valuable given the 'deprecated' name. It also does not address how the optional stripe parameters interact or the response format, though the latter is absent from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all three parameters. The description's phrase 'by stripeId' is ambiguous because the schema includes both customerId and subscriptionId as Stripe-related IDs; it does not clarify which specific parameter is meant. It also restates companyId without adding meaning, so it fails to enhance parameter understanding and may introduce confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get locations') and the criteria ('by stripeId with companyId'). It does not explicitly differentiate from the non-deprecated sibling saas_api_locations or other saas tools, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an important usage constraint ('requires an agency-level token, not a location PIT'), which helps the agent decide when authentication is appropriate. However, it does not explicitly compare against alternatives like the non-deprecated saas_api_locations, nor does it state when to prefer this deprecated variant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a write operation (readOnlyHint=false) and not destructive. The description matches this by stating 'Pause location', a state change. It adds the token requirement as behavioral context. No contradiction with annotations. It does not disclose any side effects or reversibility, but given the simple nature, the description is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise—a single sentence that front-loads the primary action and an essential usage constraint. Every word adds value, making it a model of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three parameters and no output schema, the description covers the primary action and a key prerequisite. However, it omits any mention of the deprecated status or the existence of the non-deprecated sibling, which is important contextual information for an agent deciding which tool to use. This gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with minimal per-parameter descriptions ('Paused', 'Company ID', 'Location ID...'). The main description does not add additional meaning to these parameters, but since the schema already documents them, the description's lack of parameter detail is acceptable. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Pause location'. It adds a critical context note about the required token type. However, it does not distinguish itself from its non-deprecated sibling tool 'saas_api_pause_location', and the name 'deprecated' is not reflected in the description, leaving the agent to infer the difference from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific usage condition: 'requires an agency-level token, not a location PIT'. This is useful guidance. However, it does not explicitly mention the non-deprecated alternative or when to prefer one over the other, leaving the agent to guess which version to call.
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, covering the safety profile. The description adds value beyond those by disclosing an authentication requirement (agency-level token vs location PIT), which is a behavioral trait not present in the structured metadata. It does not describe the response format, but with annotations handling the safety aspects, the added context is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action ('Get Last Snapshot Push') and follows with the key authentication constraint. There is no redundant phrasing or filler, making it highly efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with annotations covering safety and a schema that documents the optional locationId, the description adds the essential auth requirement. However, it omits any explanation of what a 'snapshot push' is, how the parameters relate to the operation, or what the return value contains (no output schema exists). The lack of differentiation from the sibling snapshots_get_snapshot_push also leaves ambiguity, making it only marginally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% – only locationId has a description in the schema. The tool description provides no information about snapshotId or companyId, failing to compensate for the low coverage. The agent is left without guidance on how to fill these parameters beyond their names and types, which is insufficient for a tool with two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and object 'Last Snapshot Push', making the purpose unambiguous. It also adds a specific constraint about the required token type, which helps distinguish it from similar read operations. However, it does not explicitly contrast with the sibling tool snapshots_get_snapshot_push, relying on the word 'Last' to imply the differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage condition: 'requires an agency-level token, not a location PIT', telling the agent when this tool is appropriate in terms of authentication context. It does not mention any alternative tools or explicitly state when NOT to use it, so the guidance is limited to a prerequisite rather than a comparison with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'paginated' behavior and 'all' scope, which is useful but doesn't elaborate on return format or pagination token mechanics. Given annotation coverage, this adds moderate 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action ('Get all'), resource ('knowledge bases'), and key constraints ('for a location', 'paginated'). No filler or redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional pagination parameters, the schema fully documents each parameter and annotations cover safety. The description clarifies it returns all knowledge bases for a location. While it doesn't detail defaults for limit or the exact pagination token usage, such details are minor and the tool is straightforward enough to be effectively used.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions covering their meaning (limit, query, locationId, lastKnowledgeBaseId). The description adds no extra semantics beyond noting location scope and pagination, which is already implied by the schema. With 100% schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states the verb 'Get', the resource 'knowledge bases', and the scope 'for a location by location Id' with '(paginated)' indicating pagination behavior. This clearly distinguishes it from knowledge_base_get_knowledge_base_by_id (single record) and knowledge_base_list (broader retrieval). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like knowledge_base_list or knowledge_base_get_knowledge_base_by_id. While it implies usage for a specific location, it does not mention exclusions or alternatives, leaving the agent to infer the correct choice from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true and readOnlyHint: false, so the description's 'Delete' is consistent and adds no new behavioral information. The description does not contradict annotations, but it also doesn't elaborate on consequences (e.g., whether deletion is irreversible or affects related data). With annotations covering the safety profile, a neutral score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and object. There is no fluff or redundant information, making it appropriately sized for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no output schema, and annotations covering destructive behavior, the description is complete for basic use. It doesn't elaborate on edge cases (e.g., error handling if charge doesn't exist), but given the simplicity and existing schema/annotations, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for chargeId ('ID of the charge to delete'). The tool description adds no further meaning beyond what the schema already provides, so it meets the baseline without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Delete') and resource ('wallet charge'), which directly distinguishes it from sibling tools like marketplace_get_charges and marketplace_charge. Even though it's brief, it leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. There is no discussion of when not to use it or what other operations might be more appropriate, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context such as authentication requirements, rate limits, or what happens if the charge ID is invalid. With annotations present, the description's minimalism is acceptable but does not exceed the baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single short phrase, 'Get specific wallet charge details', which is concise and front-loaded. Every word is necessary; no filler or redundant content. For a simple get-by-ID operation, this is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, read-only, no output schema), the description is largely complete. An agent can infer it returns the details of a specific wallet charge. However, it does not explicitly mention what 'details' includes or any potential error conditions, but for a straightforward retrieval this is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the only parameter 'chargeId' has a description 'ID of the charge to retrieve'. The tool description does not add any extra meaning beyond what the schema already provides. Since the schema does the heavy lifting, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get' and the resource 'specific wallet charge details', unambiguously indicating a single-charge retrieval. It implicitly distinguishes from sibling marketplace_get_charges which suggests listing all charges. The name and description align well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like marketplace_get_charges or marketplace_charge. Does not specify any prerequisites or mention that this is for a specific charge by ID, though the parameter hints at that. Lacks exclusions or alternate routes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it retrieves all objects for a location, which is essentially the function. It does not disclose nuances like pagination, response size limits, or empty-list behavior. This is acceptable given the simple read-only nature, but it adds little 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core function with no superfluous wording. It is appropriately concise and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one optional parameter and read-only annotations, the description is largely sufficient. It implies a collection result ('all objects') and the default location behavior is covered in the schema. However, it does not mention response format or limitations, which would assist an agent, but the lack of an output schema is mitigated by the straightforward nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the one parameter (locationId) with its description and default behavior (defaults to GHL_LOCATION_ID when omitted). Since schema coverage is 100%, the description does not need to add parameter details. It provides no additional semantic meaning beyond the schema, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all objects for a location' clearly states the action (get), the resource (objects, likely custom object records), and the scope (by location). It distinguishes from sibling tools like objects_get_record_by_id (single record) and objects_search_object_records (search with filters) by implying a bulk fetch for a location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as objects_search_object_records or objects_get_record_by_id. The description does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds a crucial behavioral detail: it requires an agency-level token and explicitly warns against using a location PIT. This is valuable context about authentication that the schema/annotations do not cover. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, highly focused sentence. The core purpose and a critical auth requirement are front-loaded. No filler words or redundant information. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with only two parameters and no output schema, the description covers the essential behavioral requirement (auth token type). Combined with annotations and the partial schema, an agent has enough to invoke it correctly. It does not describe return format, but that's not critical for a straightforward get-details tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is exactly 50% (locationId has a description, companyId does not). The description adds no parameter-level detail whatsoever. It does not explain what companyId refers to or how to provide locationId beyond what the schema already states. With partial coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('Location Subscription Details'), making the tool's purpose unmistakable. It also includes an important auth caveat. However, it does not explicitly differentiate from similar siblings like saas_api_get_saas_plan or saas_api_get_saas_locations, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (agency-level token, not location PIT) which helps the agent understand when this token type is required. However, it gives no guidance on when to choose this tool over the many saas_api siblings, nor any exclusions. The context is useful but not full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the token requirement as an operational detail, but does not disclose return formats, pagination, or error conditions. With annotations handling the core behavioral traits, the one extra detail justifies a 3, though richer context would be welcome.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, extremely concise and front-loaded with the main action. It wastes no words and immediately gives the critical prerequisite. While it may be too terse, it earns high marks for conciseness and structural efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what the tool returns, but it doesn't. It also omits parameter details, does not clarify how to obtain planId and companyId, and lacks context on when to use this versus the deprecated variant. Given the complexity of the SaaS domain and the missing information, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. The description does not mention planId or companyId at all, nor their formats, sources, or constraints. Since the parameter names are only nominally self-explanatory and no additional guidance is provided, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'SaaS Plan', making the purpose explicit. It also distinguishes itself from location-level operations by specifying 'requires an agency-level token, not a location PIT', which helps differentiate it from sibling tools like saas_api_get_location_subscription.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage condition (agency-level token required, not a location PIT), which implicitly tells agents when this tool is appropriate versus alternatives that operate on location-level tokens. However, it doesn't explicitly name alternative tools or state 'use this when...', so it's slightly less directive than ideal.
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 a key behavioral constraint beyond annotations: the token requirement. Since annotations only provide readOnlyHint=false and destructiveHint=false, they don't mention auth. The description reveals an operational prerequisite that could prevent failed calls. It doesn't mention deprecation status (only in name) or other side effects, but the auth note adds meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the most important non-obvious information (the token requirement). It avoids redundancy with the schema and is to the point. While brief, it's efficiently structured without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description doesn't mention that this is a deprecated endpoint or point to the non-deprecated alternative, which could lead an agent to select it unknowingly. It also doesn't describe expected return values or success criteria, though the schema clarifies inputs. Overall, it provides enough to make a call but omits important contextual warnings about deprecation and alternative tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (companyId, product, locationIds, config) having descriptive text. The description itself adds no parameter-specific information; it only mentions token types, which is an auth requirement rather than a parameter detail. Hence, baseline 3 is appropriate since the schema already documents parameter meanings effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Update Rebilling') on a specific resource, and the name reinforces it. It doesn't explicitly say what rebilling is or list the fields, but the intended purpose is unambiguous. Differentiation from siblings is weak because the non-deprecated saas_api_update_rebilling exists without any qualifier, but the deprecated suffix in the name hints at that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes one critical usage guideline: it requires an agency-level token, not a location PIT. This tells the agent when the tool is usable in terms of auth context. However, it does not advise preferring the non-deprecated sibling or explain scenarios where this deprecated version should be used, leaving the agent to infer based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (write operation), idempotentHint=false, and destructiveHint=false. The description adds the auth requirement, which is more of a usage guideline than a behavioral trait. It does not disclose any additional side effects, return values, or consequences of creation. With annotations covering basic traits, this is adequate but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no extraneous words. It front-loads the action and includes a quick auth note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is very minimal. It does not explain what creating a custom object schema entails (e.g., defining labels and primary display property) or what the agent should expect after success. While the schema provides full parameter documentation, the description lacks context about the purpose and outcome of the operation. For a create tool with nested objects, more context would be helpful, but it's not severely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented. The tool description adds no parameter-specific information. Per the rubric, with high schema coverage, the baseline is 3, and the description does not go beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create Custom Object' which is a clear action and resource, but it does not explicitly mention 'schema' or 'definition'. This could be ambiguous because sibling tool 'objects_create_object_record' also creates a custom object (a record). The tool name includes 'custom_object_schema' but the description alone doesn't clarify this distinction. It's close to 5 but falls short on specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a usage constraint: 'requires an agency-level token, not a location PIT'. This tells the agent when it can use this tool (with agency-level auth) and when it cannot (with only location PIT). It does not mention alternatives or when to prefer other tools, but the auth prerequisite is a clear and useful usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the authentication context (agency-level token) which is useful, but does not mention side effects, response shape, or any other behavioral details. With annotations covering the safety profile, the description provides marginal value, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly states the purpose and the key prerequisite. It contains no filler or redundant details, and the most important info (token type) is front-loaded. Perfectly sized for the task.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters including optional scoping parameters (share_location_id, relationship_number) and an enum for share_type, the description offers no guidance on when to use these options. The schema provides some descriptions, but the description body doesn't explain the differences or expected behavior. Given the lack of an output schema and the parameter nuances, more contextual detail would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so most parameters are documented in the input schema with descriptions (except companyId). The description itself adds no parameter-specific information. Since the schema does the heavy lifting, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Create) and resource (Snapshot Share Link), making the tool's purpose unambiguous. It also adds a critical prerequisite (agency-level token) that distinguishes it from typical location-based operations. The name and description together differentiate it from sibling snapshot tools (which are 'get' operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a required token type but does not explicitly state when to use this tool versus alternatives or when not to use it. It implies usage for creating share links, but no guidance is given on choosing among share types or comparing with related snapshot functions. The context is clear from the resource, but lacks explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which convey that this is a safe, non-mutating read. The description adds no additional behavioral context such as return format, error handling, or any side effects. With annotations covering the safety profile, the description's lack of extra detail results in a moderate score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the key action and target. There is no fluff or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward fetch-by-ID tool with one parameter and annotations indicating a safe read, the description is sufficiently complete. It doesn't cover return format or error cases, but these are not critical for an agent to call the tool correctly in most scenarios. The absence of an output schema is compensated by the simplicity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the parameter id as 'Path parameter id' with 100% coverage, and the description reiterates 'by message id' without adding format, type, or meaning beyond the schema. Since the schema already documents the parameter adequately and the description adds nothing significant, 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/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get'), resource ('message'), and the identifying criterion ('by message id'). It is immediately distinguishable from sibling tools like conversations_get_messages (plural, likely list) and conversations_get_email_by_id, as it targets a single message by its unique ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate use (fetching a specific message when you have its ID) but does not explicitly contrast with alternatives like conversations_get_messages or conversations_get_email_by_id. There is no 'use when...' or 'instead of...' guidance, leaving the agent to infer when this tool is preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, so the destructive nature is known. The description adds the token-level requirement, which is not in annotations and is useful. It does not elaborate on irreversibility or side effects, but with the destructive hint and idempotent hint present, the added value is minimal but relevant. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loads the action, then adds the essential token requirement. There is no redundant wording or filler. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 the core purpose and a key authentication detail. It does not mention permanence or cascading effects, but the destructiveHint annotation already signals that. The token requirement is the missing piece that the description supplies, making it sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a description for customMenuId: 'ID of the custom menu to delete', which is clear and complete. The tool description does not add extra semantics beyond that. Since schema coverage is 100%, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action explicitly: 'Delete Custom Menu Link'. It clearly identifies the resource and the operation, and it is distinguishable from sibling tools like custom_menus_create_custom_menu or custom_menus_update_custom_menu. 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical usage prerequisite: 'requires an agency-level token, not a location PIT'. This helps the agent know when it can be used. However, it does not mention when to prefer deletion over update or other alternatives, nor does it describe any conditions for deletion eligibility. It gives a necessary constraint but lacks comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and side-effect profile. The description adds no behavioral context beyond these, and does not contradict them. It could mention that results depend on training status or that it returns a list, but with annotations covering the core, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence: 'Get all trained page links by knowledge base'. It is front-loaded with the action and resource, contains no fluff, and every word earns its place. Perfectly compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool, the description plus schema and annotations provide sufficient information. It does not explain that the query parameter filters URLs or that pagination is supported, but those are discoverable in the schema. There is no output schema, but the return type (list of links) is inferable from the description. The tool is straightforward, and the description is adequate, though it could mention filtering/pagination in a sentence for extra clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (page, query, locationId, pageLength, knowledgeBaseId) already has a description. The tool description adds no additional semantic meaning beyond what the schema provides. It does not explain relationships between parameters or defaults, but the schema already does the heavy lifting. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'all trained page links', and the scope 'by knowledge base'. It is specific enough to distinguish from sibling tools like knowledge_base_get_knowledge_base_by_id or knowledge_base_list_all_knowledge_bases_paginated, as it refers to the trained URLs associated with a knowledge base.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: retrieve trained page links for a knowledge base. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any prerequisites like the knowledge base needing to be trained. It provides no guidance on filtering or pagination, which are available via parameters, but that is more about parameter semantics. Overall, the usage context is implied but not expanded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds the pagination behavior, which is not in annotations. However, it does not describe response format or edge cases, so it adds only modest 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose. It contains no filler and is immediately clear. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers parameter meanings and annotations cover safety, the description is nearly sufficient. It clearly indicates the tool returns all FAQs for a knowledge base with pagination, which is the core intent. The lack of output schema is acceptable for a list operation, and the description does not omit anything critical for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the schema (100% coverage). The description does not add additional meaning beyond the schema, such as how pagination works or the default for locationId. It relies on the schema for parameter details, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get all FAQs by knowledge base'. This clearly distinguishes it from sibling tools like knowledge_base_list_all_knowledge_bases_paginated (lists knowledge bases, not FAQs) and knowledge_base_get_knowledge_base_by_id (gets a single knowledge base). The required knowledgeBaseId parameter reinforces that it operates on a specific knowledge base.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly specify when to use this tool vs alternatives. It mentions pagination support but does not state when to prefer this over other knowledge base tools. It is not misleading, but the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the auth requirement (agency-level token vs location PIT), which is a useful contextual detail beyond the annotations. However, it does not describe what happens to associated data or the irreversible nature of deletion, though the destructive hint partially covers this. Overall, it provides some added context but not extensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise clause, front-loaded with the core action and terminology clarification followed by the critical auth note. It is efficient and contains no fluff. However, it is very terse and could be structured as a sentence, but it still conveys necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters, but it is a destructive, idempotent operation with a specific auth requirement. The description covers the auth requirement, which is crucial, but it does not mention the effect on related data or the absence of an output schema. Given that the annotations flag destructive and idempotent, the description is minimally sufficient but could benefit from a note about permanence or cascading effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters (locationId and deleteTwilioAccount) have descriptive text in the schema. The description does not add extra meaning about parameters, but since the schema fully documents them, the baseline of 3 applies. No compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete Sub-Account (Formerly Location)'. This clearly identifies the action and the target entity, and clarifies the terminology difference (sub-account vs location), distinguishing it from other delete operations like locations_delete_tag or contacts_delete_contact. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage constraint: 'requires an agency-level token, not a location PIT'. This tells the agent when it is appropriate to use this tool (with agency-level credentials) and implicitly when not (with a location PIT). It does not name specific sibling alternatives, but among the many delete tools, this auth note is a strong routing cue.
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 the important constraint that an agency-level token is required, not a location PIT, which is not present in the annotations. It does not describe side effects or the exact nature of the mutation, but the annotations already indicate it is not read-only. The added auth detail enhances transparency beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action and resource, then appends the crucial auth requirement. No redundant information or filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the schema's parameter details, provides enough information for an agent to invoke the tool correctly. It could be more explicit about the distinction from bulk enable, but the singular 'Location' and the absence of 'bulk' make it reasonably clear. The auth requirement is crucial and well-stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has high description coverage (92%) and each parameter is individually described, so the description adds no additional parameter meaning. With this coverage, a baseline of 3 is appropriate; the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Enable SaaS') and the target resource ('Sub-Account (Formerly Location)'), distinguishing it from bulk operations and deprecated versions by implying a single-location operation. It also includes a critical requirement (agency-level token), which adds precision beyond the name itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (agency-level token) but does not specify when to use this tool versus alternatives like saas_api_bulk_enable_saas or the deprecated variant. No exclusions or alternative suggestions are provided, leaving usage context implicit.
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, and destructiveHint=false, so the safety profile is covered. The description adds a behavioral constraint not in annotations: the requirement of an agency-level token (vs. a location PIT). This is useful context that affects call success and aligns with the read-only nature. It does not contradict annotations and adds value beyond the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the purpose and the key constraint without fluff. It front-loads the action and then the token requirement, with no wasted words. Perfectly sized for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description is adequate for a read-only get tool with a detailed schema, it lacks information about the return type or structure. The presence of skip/limit parameters suggests pagination and multiple locations, but the singular 'Location' in the name creates ambiguity. With no output schema, the agent cannot infer the response format. The description also doesn't mention whether the result is a single object or a list, which could affect how the agent uses the tool. The token constraint is stated, but response semantics are left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 10 parameters have descriptions in the schema. The description itself does not add meaning to parameters, which is acceptable given the high coverage. It implicitly references the token requirement but does not explain any parameter syntax or relationships. Baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('Location where app is installed'), and adds a specific usage constraint (requires an agency-level token, not a location PIT). This goes beyond a generic statement and clearly distinguishes it from other tools in the sibling list, which focus on other aspects (e.g., saas plans, ad management). The purpose is unambiguous and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite (token type) but does not explicitly state when to use this tool versus alternatives. There is no mention of conditions that would point to another tool or exclusions. The token requirement provides context, but no explicit 'use this when...' guidance is offered, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the authentication constraint (agency token) which is useful context, but doesn't elaborate on behavior such as pagination or response structure. With annotations carrying the safety burden, a modest score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One clean sentence that states the purpose and the key prerequisite, with zero filler. It front-loads the essential information and is highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with fully documented parameters and annotations covering safety, the description provides the necessary context: what it does and who can use it. It doesn't need to explain return values since no output schema exists and the operation is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 5 parameters are already documented with descriptions. The tool description adds no additional parameter context, so it doesn't exceed the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Custom Menu Links' with a specific verb and resource, and the parenthetical about agency-level token distinguishes this from location-specific operations. It stands apart from siblings like custom_menus_get_custom_menu_by_id, so purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that an agency-level token is required and not a location PIT, which is crucial for correct invocation. It doesn't explicitly name alternatives like the get-by-id sibling, but the plural scope and token requirement imply when to use this over other custom menu tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive, so the description's main added value is the specific authentication requirement, which is important context beyond the annotation. It does not contradict any annotation; instead, it enriches the safety profile with a concrete constraint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that delivers the core function and a critical requirement with no extraneous information. It is well-structured and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple filter-by-email tool, the description, combined with schema and annotations, covers the essential information needed to call it correctly. The only minor gap is that it does not mention the default return format (id and email) or pagination behavior, but these are implied by the projection parameter and skip/limit parameters in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with each parameter clearly documented (e.g., comma-separated emails, projection defaults). The description adds no further parameter-level detail, so it relies on the schema, which is adequate for baseline scoring.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Filter Users by Email') and the resource (Users), which distinguishes it from other user tools like searching or getting a single user. It also adds a specific constraint (agency-level token vs location PIT), 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a critical usage prerequisite: it requires an agency-level token, not a location PIT. However, it does not explicitly mention when to prefer this over alternatives like users_search_users or when not to use it, leaving some inference to the agent.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/AIWerk/mcp-server-ghl'
If you have feedback or need assistance with the MCP directory API, please join our Discord server