Zendesk MCP Server

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation5/5
Each tool has a clearly distinct purpose, and descriptions explicitly differentiate between similar tools (e.g., find_field_usage vs audit_field_health). Agents should rarely misselect.
Naming Consistency5/5
All tool names follow a predictable verb_noun pattern (audit_, find_, get_, list_, set_, etc.) with consistent snake_case. No mixing of styles.
Tool Count2/5
With 74 tools, the server is extremely large. While each tool serves a specific function, the sheer number is excessive and could overwhelm an agent. The domain is broad but could be consolidated.
Completeness4/5
The tool set covers Zendesk inspection comprehensively: tickets, users, triggers, fields, tags, SLA, routing, etc. Missing write operations (create/update/delete) is acceptable given the server's apparent focus on analysis and audit.
Average 4.5/5 across 74 of 74 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 6 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read behavior is documented. The description adds value by specifying that the tool returns 'full body' including signature template and host mapping, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb, no wasted words. Perfectly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch-by-ID tool, the description is fairly complete, mentioning the key returned components. However, it could be slightly more explicit about what 'full body' entails, but given the lack of output schema, it's acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, both parameters have descriptions in the schema. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch one brand by ID') and resource, and distinguishes from sibling list_brands by specifying 'one brand by ID'. It also adds context about the full body (signature template, host mapping), which clarifies 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like list_brands. Usage is implied by the purpose (fetch by ID) but no exclusions or alternative mentions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral context: it returns the 'full permission grid' and is 'Enterprise-plan-gated', which are beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no waste. The action and key points are front-loaded: 'Fetch one custom role by ID with the full permission grid'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool, the description covers purpose, scope, and plan gating. It lacks details on error behavior or return structure, but given the lack of output schema and 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema describes both parameters fully (100% coverage). The description mentions 'by ID' which aligns with the id parameter but adds no additional meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch'), the resource ('custom role'), and the specific scope ('by ID with the full permission grid'). It distinguishes from list_custom_roles by specifying a single role with full details, and adds the Enterprise-plan gating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Enterprise-plan-gated' which gives context on availability, but it does not explicitly state when to use this versus alternatives (e.g., list_custom_roles) or when not to use it. Usage is implied but not detailed.
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 and idempotentHint. The description adds critical behavioral traits: plan-gating (degrading to upstream_error without Chat add-on) and scope-gating (when chats include user/ticket data). This goes beyond annotations and helps the agent understand constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences, no fluff. However, it uses technical jargon like 'skeleton projection' and 'Plan-gated' which may hinder readability for some agents. Still, it efficiently conveys key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return value shape beyond 'native shape'. Since there is no output schema, the description should provide more context about what fields or structure to expect. The parameter descriptions are complete, but the response format is underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with detailed descriptions for each parameter. The description only mentions 'limit', 'cursor', 'fields', and 'filter' as options, adding no new semantics beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Zendesk Chat conversations as paginated items in their native shape, distinguishing it from other list tools that target different resources (e.g., tickets, users). The mention of 'no skeleton projection' and 'compact chat payloads' further clarifies the resource specifics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on pagination, default limit, and options to pass cursor/fields/filter. It also mentions plan-gating (requires Chat add-on) and scope-gating, which imply when to use. However, it does not explicitly state when not to use or compare to sibling tools like list_tickets.
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 openWorldHint. The description adds context about being a convenience wrapper and plan-gating, but does not disclose caching behavior or other implicit traits beyond what is already in 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 4 sentences, front-loaded with the purpose, and every sentence adds value: purpose, parameter guidance, rationale, and alternative tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, 100% schema coverage, and no output schema, the description provides sufficient context—purpose, key parameters, alternative, and plan restriction. It mentions 'skeletons' which hints at the output, but could be more explicit about return structure. Still, it is complete enough for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, e.g., emphasizing case-insensitivity and defaults for attribute_name, but these are largely already captured in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a convenience wrapper that resolves a 'skills'-like routing attribute and returns its values as skeletons. It specifies the key parameters (attribute_id and attribute_name) and distinguishes itself by explaining it exists because LLMs ask for 'skills' by name, with an explicit alternative (list_agent_skill_assignments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'For agent assignments use list_agent_skill_assignments' and notes the tool is plan-gated, providing clear when-to-use guidance. It also hints at the underlying mechanism (list_routing_attribute_values) but does not explicitly state when to prefer this tool over list_routing_attribute_values.
Agents often have multiple tools that could apply. Explicit usage guidance like "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 add behavioral context beyond what annotations already provide (readOnlyHint, openWorldHint, idempotentHint). It simply restates the purpose without disclosing any additional behavioral traits like auth requirements 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence states the purpose, the second provides an alternative tool reference. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch-by-ID tool with one required parameter and annotations covering safety, the description is complete. It tells what it does and offers a pointer to a related tool, which is sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented. The description only mentions the 'id' parameter implicitly, not adding meaning beyond the schema. The baseline of 3 is appropriate as the schema already handles parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'one custom ticket status by ID'. It also distinguishes itself from siblings by directing users to `find_triggers_by_field` for related queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (fetch by ID) and when not to (use `find_triggers_by_field` for which rules set this status). This provides clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld; description adds locale variant detail and plan constraint, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste, front-loaded with action and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with full schema and annotations, description provides all necessary context: what, how (by ID), what returned (locale variants), and constraint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions; description adds no additional parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states fetching one dynamic content item by ID with all locale variants, distinguishes from list_dynamic_content sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions plan-gating to Professional+, providing a clear constraint; usage vs alternatives is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, openWorld, and idempotent behaviors. The description adds transparency about the snapshot nature and plan-gated degradation to an error envelope, which goes beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core purpose and then adding necessary caveats. It is concise but could be slightly more streamlined. Still, it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema), the description adequately explains the return type (snapshot with specific metrics) and the error condition. It could mention the output format more explicitly, but it's sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage for both parameters (refresh and instance). The tool description does not add any additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches a current account-overview snapshot for Zendesk Talk, listing specific metrics like average wait/handle time, calls in queue, agents online. It distinguishes itself from historical analytics by directing users to Explore. The verb 'Fetch' and resource 'account-overview snapshot' are specific and unique among sibling tools, which lack any talk-specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions plan-gating and error behavior, indicating when the tool may not work. It also suggests using Explore for historical analysis, providing context. However, it lacks explicit 'when-to-use' vs alternatives, but since no sibling talk tool exists, the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral details: tolerance of per-kind upstream errors with 'notes' and skipping system fields. This provides useful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two efficient sentences packed with specific, useful information. It is front-loaded with the core purpose and uses concise phrasing without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a composite audit tool with no output schema, the description covers the key aspects: what issues are flagged, what is skipped, and error tolerance. It lacks details on output format but is 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (refresh, instance) are fully described in the input schema (100% coverage). The description adds no additional parameter-specific semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a composite ticket-field hygiene report, listing specific issues (unreferenced fields, fields in inactive rules, dropdowns with empty options, custom fields not on active forms) and what it skips (system fields). It distinguishes itself from siblings like find_field_usage by bundling multiple checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions itself as 'the right starting point for field-cleanup work' and explains that it bundles find_field_usage plus additional checks, giving clear context for when to use it. However, it doesn't explicitly state when not to use it or list other alternatives beyond find_field_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 declare readOnlyHint, openWorldHint, and idempotentHint, so the description does not need to repeat those. However, it adds no extra behavioral detail beyond the annotations, such as potential rate limits 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the core purpose, and the second provides an alternative use case. No superfluous words, achieving high information density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch-by-ID tool with two parameters and no output schema, the description is sufficient. It covers the purpose, scope, and provides guidance for related tools. Could optionally mention the expected return format but is not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters adequately. The description reinforces the 'id' parameter but adds no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one automation by ID with full conditions and actions', using a specific verb and resource, and distinguishes from sibling tools by mentioning the 'find_*_usage' analyzers for impact analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use an alternative: 'For impact analysis on referenced fields/forms/groups, use the corresponding find_*_usage analyzer.' This provides clear context for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld hints. Description adds plan-gating and specific error degradation behavior, providing meaningful context beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose. Second sentence adds behavioral context and sibling reference. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema, but describes plan-gating and error behavior. Return format not specified, but for a simple fetch tool this is adequate. Could be improved with response description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. Description only mentions ID parameter, no additional meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb ('fetch') and resource ('routing attribute definition by ID'). Differentiates from sibling tools like list_routing_attributes and list_routing_attribute_values by specifying ID lookup and explicitly directing to the sibling for values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: plan-gated, degrades on 403/404 when feature is off. Also tells when to use sibling tool for values. Lacks explicit 'when not to use' but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds behavioral insight that holidays are not included and recommends alternative. No contradiction; valuable beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two clear sentences with no fluff. First sentence states core purpose, second provides critical guidance in bold. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple read-only tool with good annotations, description covers what is returned (intervals) and what is not (holidays). Lacks a brief response structure mention but adequate for invocation decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (id, instance). Description adds no additional parameter semantics beyond stating the response includes intervals, which is about the return value, not parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Fetch' and resource 'one schedule by ID', and mentions included data 'weekly intervals'. It distinguishes from list_schedules (multiple) and explicitly contrasts with list_business_hours for holidays.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when not to use (if holidays needed, use list_business_hours) and why. Could be improved by mentioning alternative for listing all schedules, but the guidance is clear for the common case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds that the fetch includes full filter and policy_metrics, giving additional context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. First sentence states purpose, second provides a clear alternative usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the tool's purpose and an alternative. With annotations present, it provides sufficient context for a simple fetch tool, though it could mention that it returns a single policy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already documents parameters. Description does not add semantics beyond stating 'by ID' for the id parameter. No extra detail for instance parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches one SLA policy by ID with full filter and policy_metrics. Distinguishes from sibling find_group_usage by providing an alternative use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use find_group_usage instead, but does not provide guidance on when to use this tool vs. list_sla_policies or other 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 declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds the return context (ordered list of ticket_field_ids) but does not elaborate on other behavioral traits such as auth requirements or rate limits. Given annotation coverage, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, minimal waste. First sentence delivers action and primary output clearly; second sentence provides alternative usage guidance. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (fetch by ID) with full schema coverage, but no output schema exists. The description adequately explains what is returned (ordered ticket_field_ids) and provides usage context. No major gaps, though it could be more explicit about the structure of the return if needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning to parameters; it focuses on output and usage. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one ticket form by ID with the full ordered list of `ticket_field_ids`', specifying the verb, resource, and unique output. It distinguishes from sibling 'find_form_usage' by stating a different use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('Fetch one ticket form by ID') and when to prefer an alternative ('For impact analysis before retirement, prefer `find_form_usage`'), providing clear context-sensitive 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 readOnlyHint, openWorldHint, and idempotentHint. The description adds the distinction from user field values but does not disclose additional behaviors such as error handling, rate limits, or pagination. Given the annotations, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and contains no wasted words. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool with 2 parameters and no output schema, the description covers the essential context: what it does, when to use it, and how it differs from a related concept. It does not describe error cases or return structure, but that is acceptable given the tool's simplicity and the presence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description does not add extra meaning beyond stating 'by ID', which is already implied. It does not elaborate on the id or instance parameters, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches a user-field schema entry by ID with full body, using a specific verb and resource. It explicitly distinguishes this from fetching a user field value on a user, differentiating it from sibling tools like get_user and list_user_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use this tool to fetch a schema entry, but for a field value on a user, instead fetch the user and read user_fields. This helps the agent choose correctly among siblings like get_user.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral details beyond annotations: plan-gating, pagination, projection options. Annotations already indicate readOnly, idempotent, openWorld; description does not contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains return value (skeleton fields), pagination, plan-gating. Without output schema, covers essentials; could mention pagination token in response explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline 3. Description summarizes key parameters and default limit but adds limited new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states returns brands as paginated skeletons with specific fields. Distinguishes from sibling 'list_' tools by mentioning plan-gating and that brand lists are tiny, straight enumeration is fine.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on plan-gating and that enumeration is fine, but does not explicitly compare to alternatives like get_brand or other list 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 declare readOnly and idempotent hints. The description adds behavioral details: pagination with default limit 100, server-side caching with stale cursor auto-reset, field filtering, verbose mode, and cache bypass via refresh. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact paragraph with no wasted words. The core purpose and key parameters are front-loaded, and the alternative tool call is highlighted with bold text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema), the description covers return structure, pagination, caching, filtering, and usage guidance. Minor omission: the `default` field in the skeleton is not explained. Overall, sufficient for an agent to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3. The description adds minimal extra context beyond the schema, such as the default limit and cursor auto-reset behavior, but mostly reiterates param usage. No significant value added over schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'returns' and the resource 'agent groups', specifies the skeleton fields, and distinguishes from sibling tool `find_group_usage` by noting when to use that instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends calling `find_group_usage` when checking deletion safety, providing an alternative. It also notes the typical small size of group lists, implying that filtering is often unnecessary. However, it could be more explicit about when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds useful behavioral context: pagination details (default limit, cursor behavior, caching), plan-gating, and the ability to use fields, filter, verbose, refresh. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two well-structured sentences. It front-loads the main purpose and includes key details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema), the description covers the core behavior, pagination, caching, plan-gating, and an alternative tool. It does not explain return values, but that is acceptable as per rules since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds only a high-level overview (e.g., default limit, cursor usage). It does not provide new semantic meaning beyond what the schema already offers, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns values under a routing attribute as paginated skeletons, and it distinguishes from the sibling tool list_agent_skill_assignments by mentioning its use case for seeing which agents have a given value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case and suggests an alternative tool (list_agent_skill_assignments). It also notes the plan-gating and degradation condition, giving context for when the tool may not work. However, it does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent. Description adds that it returns http_status, timing, and outcome, which gives insight into the output behavior beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose and key parameters, second emphasizes diagnostic use, third gives alternative tool. No redundancy, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return fields (http_status, timing, outcome). However, it doesn't mention that the response includes a list or pagination details, but the parameter descriptions cover cursor. Almost complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description only names a few parameters (limit, cursor, fields, filter) without adding new meaning 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns delivery history for one webhook with specific fields. It distinguishes itself from list_audit_logs, but not from all other list_* tools, so not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'The right tool for "is this webhook actually working?"' and provides a when-not alternative: 'For instance-wide configuration changes, use list_audit_logs.' This offers clear guidance on when to use and when to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral detail: it tolerates per-kind upstream errors with notes in the output, and a missing trigger list is fatal. This gives the agent important context on error handling beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded with the list of checks. It is concise but includes a bold phrase that, while emphasizing usage, could be considered slightly redundant. Overall, it is well-structured and efficient with minimal wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the report's contents (specific anomaly types) and notes that errors are listed in a 'notes' field. However, it does not detail the format or structure of the output, leaving some ambiguity. For a composite report tool, it is mostly complete but could be more explicit about return value organization.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the two parameters (refresh, instance) already described. The description does not add any additional meaning for these parameters beyond what is in the schema. According to the guidelines, baseline 3 is appropriate when schema coverage is high and description adds no extra param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a composite trigger-hygiene report listing specific checks (conflicts, deactivated but referenced, orphaned references, ordering anomalies, empty rules). It distinguishes itself from siblings like find_trigger_conflicts by noting it bundles multiple checks in one call, making the purpose explicit and unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions this as 'the right starting point for trigger cleanup work,' indicating it is a comprehensive first step. While it does not list specific alternatives or when not to use it, the context is clear and implies using this over individual check tools for an overall health report.
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, openWorldHint. The description adds no additional behavioral context beyond confirming a fetch operation. No extra disclosure is needed, so 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. Front-loaded with purpose and immediately followed by usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with full schema coverage and comprehensive annotations, the description is complete. It does not need to explain return values since no output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description does not add any further detail about parameters, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches one group by ID, with a specific verb and resource. It distinguishes from sibling tools like `find_group_usage` by implying its primary use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: before deletion, prefer `find_group_usage` over this tool. This directly helps the agent decide when to use the tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds transparency about error tolerance ('tolerates per-kind upstream errors with notes') and caching behavior ('refresh' parameter), which is valuable beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with three well-structured sentences. Uses formatting (bold, backticks) for readability. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description adequately lists all major output components (inventory, dupes, set_only, top-N) and mentions error handling. For a composite report tool, this is sufficiently complete, though a note on performance with refresh would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters, each with clear descriptions. The description adds no new parameter details beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it is a 'Composite tag-hygiene report' listing specific outputs like inventory, duplicate suspects, set_only flags, and usage distribution. It clearly distinguishes from sibling tools like find_triggers_by_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'The right starting point for tag-cleanup work' and directs users to find_triggers_by_tag for rule-specific queries. This clearly delineates when to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds operational detail: 'Operates over the cached verbose corpus, no extra HTTP.' No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then details, then usage guidance. Efficient but could be slightly tighter. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema, the description explains what results contain (conflict pairs with classes), cache behavior, and usage context. References sibling for broader report. Fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description repeats schema info for trigger_id and include_inactive but does not add new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific purpose: 'Surface pairs of active triggers that fight each other, same all-block precondition signature with contradicting effects.' It names two conflict classes and distinguishes from sibling tool `audit_trigger_health`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Pass trigger_id to scope to conflicts involving one rule, or include_inactive: true for cleanup audits.' Also directly recommends sibling: 'For a full trigger hygiene report... call audit_trigger_health instead.'
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 readOnlyHint, openWorldHint, idempotentHint. The description adds scope-gated detail (config_plus_audits or full) which is valuable context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second provides alternative. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema defined, but for a simple fetch operation, the return is implicit. The description covers identification and scope, and the alternative for other lookup methods. Adequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions for id and instance. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one organization by ID' and distinguishes from search for name/domain lookup. It specifies scope-gated behavior, which adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides an alternative: 'For lookup by name or domain, use search with type:organization.' This gives clear guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds useful context by mentioning 'full body (dropdown options, regex, etc)', indicating the depth of data returned. There is no contradiction and no missing behavioral details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose. Every word adds value, with no redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 parameters, no output schema), the description adequately covers what the tool returns ('full body') and differentiates from a key sibling. Annotations cover safety and idempotency. The description could be slightly more detailed about the return format, but it is sufficient 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described ('Ticket field ID' and 'Override the sticky instance for this call'). The description adds no additional parameter-level semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one ticket field by ID with full body (dropdown options, regex, etc).' It specifies the verb 'fetch', the resource 'ticket field', and the scope 'by ID', along with the content of the response. It also distinguishes itself from the sibling tool 'find_field_usage' by mentioning its use for impact analysis before deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states: 'For impact analysis before deletion, prefer `find_field_usage`.' This gives clear guidance on when not to use this tool and recommends an alternative, fulfilling the when-to-use aspect perfectly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds scope-gating (config_plus_audits or full) and cost comparison with audits, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with core functionality and follow-up with usage guidance. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-ticket metric reader with good annotations and schema, description covers scope, use case, and comparative cost. Slight gap: no mention of return format or pagination, but likely unnecessary for single record.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters (id, instance). Description adds no additional parameter-level semantics, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches the ticket_metric record for one ticket, listing specific data types (reply count, times, reopens, etc.). Distinguishes from sibling get_ticket_audits by contrasting purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool for SLA/responsiveness questions and get_ticket_audits for 'why did this happen?', citing that audits have rule attribution and field-level changes while metrics are cheaper.
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, openWorldHint. Description adds context about returning 'full body' specifics, which is helpful but not essential beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently communicates purpose and usage boundaries with zero waste. Front-loaded with action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with no output schema, description adequately covers return content. Context signals and sibling list are consistent. Slight room for more behavioral details but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description does not add meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'fetch' and resource 'webhook', with specific details about included fields. It distinguishes from sibling by mentioning delivery history alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (getting full webhook details) and when to use alternative (list_webhook_invocations for delivery history).
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, openWorldHint, and idempotentHint. The description adds useful behavior details: pagination with cursor and caching, default limit, and that firing data is not exposed on standard plans. No rate limit or auth information, but sufficient beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with core purpose, then key options, then limitations and alternatives. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description explains pagination, caching, and limitations. Points to sibling tools for related tasks. Could include more on filter object semantics, but schema covers that. Adequate for agent selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description reiterates default limit and mentions optional parameters like cursor, fields, filter, verbose. It adds context about cursor staleness and caching but does not significantly enhance meaning beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns automations (time-based rules) as paginated skeletons with specific fields (`id`, `title`, `active`, `updated_at`). It distinguishes from siblings like `get_automation` (single) and `find_unused` (indeterminate for automations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use alternatives: 'For tag / field reference questions across automations + triggers + macros, prefer `find_field_usage` or `audit_tag_sprawl`.' It also notes that firing data is not exposed, so `find_unused` returns `indeterminate` for automations.
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, openWorldHint, and idempotentHint. The description adds value by explaining it is a composite that joins data from two endpoints and mentions plan-gating, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy. Front-loaded with purpose and usage guidance. Every sentence is necessary and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but description mentions return of intervals and holidays, which is sufficient. Also covers plan-gating and composite nature. Minor gap: no mention of caching or pagination, but not critical for a read-only tool with idempotentHint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a composite returning weekly intervals and holidays for one schedule. It distinguishes itself from sibling get_schedule by advising to use this tool when answering 'when is this schedule open?'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use it (instead of get_schedule) and why (Zendesk splits data across two endpoints). Also mentions plan-gating alongside schedules themselves, providing context for access control.
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, openWorldHint, idempotentHint. The description adds behavioral details about pagination (skeletons, default limit, cursor, fields, filter, verbose) and caching behavior (via schema descriptions). No contradiction with annotations. Slightly more context would be needed for a 5, but it's 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences: purpose, key parameters, sibling distinction, and alternative usage. Every sentence serves a purpose, no redundancy, and the most critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 optional parameters, no output schema, and rich annotations, the description covers output format (skeleton fields), parameter roles, and relationships to other tools. It could mention error handling or pagination limits, but overall it is complete enough 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description summarizes the key parameters and their use cases (e.g., 'for dropdown options') but does not add significant meaning beyond the schema's existing descriptions. It groups them effectively but offers limited extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns organization-level custom field schemas as paginated skeletons, explicitly listing the fields included. It differentiates from sibling tools list_user_fields and list_ticket_fields, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use this tool (schema, not values) and provides explicit alternatives: list_user_fields, list_ticket_fields for other levels, and get_organization for values. It also mentions the default limit and parameter options, giving clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context: the paginated skeleton return, default limit, and that targets have no per-call invocation log. This goes beyond repeating annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph, front-loaded with the core purpose. Every sentence adds value: legacy status, return format, default limit, alternative recommendations, and log behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters fully described in the schema and no output schema, the description covers essential context: what it returns, why to use it, and alternatives. It could explicitly mention caching behavior (already in schema) but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description text merely lists some parameters (cursor, fields, filter, verbose) without adding new semantic information beyond what the schema already provides, thus meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns 'legacy outbound targets' (URL/email integration endpoints) which are deprecated. It specifies the returned fields as paginated skeletons and clearly differentiates from sibling tools like list_webhooks, making the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'only for migration audits'. It also states when not to use it: 'Modern instances should use list_webhooks'. Additionally, it suggests an alternative for change history: use list_audit_logs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context about session scope and overriding per-call, but doesn't detail error handling or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and behavior, no redundant words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with good annotations, the description covers purpose, usage, and behavior. Could mention error cases like invalid instance name, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the name parameter as 'Instance name as defined in instances.json' (100% coverage). The tool description doesn't add further meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool locks the session onto a single Zendesk instance and distinguishes it from sibling tools like list_instances. It uses specific verbs 'Lock' and 'default'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this once per session' and advises using list_instances first if unknown. Also explains the benefit of avoiding repetition, with clear when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, open-world, and idempotent behavior. The description adds valuable context: scans cached verbose corpus with why_matched breadcrumbs and zero extra HTTP. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with examples and preference statement, though slightly verbose. Front-loaded with purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given many sibling tools, description effectively differentiates from list_triggers and find_field_usage. Explains caching and zero HTTP cost. Missing output schema details, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds meaning: 'field' is a field name, 'value' is string-coerced exact filter, 'refresh' bypasses cache, 'instance' overrides sticky. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds triggers referencing a named field, provides concrete examples, and distinguishes itself from sibling tools (list_triggers, find_field_usage).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises preferring this tool over list_triggers for field-reference questions, and directs to find_field_usage for impact analysis. Provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, fully covering safety and idempotency. The description adds the context that the tool returns 'full actions', which is consistent but does not add new behavioral details beyond the annotations. A minor missed opportunity to clarify scope, but no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core action and then provide targeted usage alternatives. Every sentence adds value; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two parameters and no output schema, the description is complete. It covers the purpose, scope ('full actions'), and provides context for when to use alternatives, which is sufficient given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning to the parameters beyond what the schema already provides (id as macro ID, instance as override). No improvement needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'macro by ID' with 'full actions'. It also distinguishes from sibling tools by providing alternative use cases, such as using find_unused for deletion safety checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: for checking if a macro is safe to delete, use find_unused; for impact analysis on referenced items, use find_field_usage, find_form_usage, or find_group_usage. This directly tells the agent when not to use this tool and which alternative to prefer.
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, openWorldHint, and idempotentHint. The description adds that the response includes 'full body (dropdown options, regex)', which gives useful detail about returned data beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, 28 words total. Front-loaded with the core purpose, followed by a critical distinction. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters (1 required) and no output schema, the description is complete. It explains the tool's action and differentiates it from a related operation, covering all necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description does not add additional meaning beyond what is in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it fetches an organization-field schema entry by ID with full body, distinguishing it from a value on an organization. It uses specific verbs and resource, and differentiates from sibling tool get_organization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly specifies when NOT to use this tool: 'Distinct from a value on an organization, for that, fetch the organization and read organization_fields.' This provides an explicit alternative and usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds that it returns 'full conditions and actions', clarifying the depth of the response. No contradictory or missing behavioral info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with core purpose, followed by usage guidance. No redundant or irrelevant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with well-documented schema and annotations, the description fully covers purpose, usage context, and return content (full conditions and actions). No gaps 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description does not add additional meaning to the parameters beyond the schema's own documentation, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Fetch one trigger by ID with full conditions and actions', clearly identifying the verb (fetch), resource (trigger), and scope (by ID). Distinguishes from sibling tools like 'list_triggers' and 'audit_trigger_health'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use: 'Use after list_triggers / find_triggers_by_*' and when not: 'For health audits over the whole trigger set, prefer audit_trigger_health'. Provides clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds that it fetches exactly one category, which is consistent and beneficial. No contradictions; minimal additional disclosure needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main purpose, no extraneous text. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with rich annotations and full schema coverage, the description is complete. It also addresses sibling differentiation, making it contextually sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing full documentation for both parameters. Description does not add further semantic value beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Fetch one trigger category by ID', specifying verb and resource. It also distinguishes from `audit_trigger_health` for a different use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (fetch by ID) and provides an alternative (`audit_trigger_health`) for category-orphan detection, guiding proper selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld. Description adds 'with full conditions' which implies comprehensive retrieval. No contradiction, but limited additional behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main purpose and then provide alternative guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (single fetch by ID) and the presence of good annotations and full schema, the description is complete. It covers the action and points to relevant alternative tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes both parameters (id and instance) with 100% coverage. Description does not add new semantics or usage guidance for parameters beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches one view by ID with full conditions. Distinguishes from siblings by directing users to alternative tools for specific queries like 'find_unused' and 'find_*_usage'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (fetch one view) and when to use alternatives (for usage checks and reference lookups). Provides direct call-outs to sibling 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 indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds value by detailing caching behavior (stale cursor auto-reset with cursor_invalidated flag), plan-gating with HTTP status codes, and server-side filter honor. Does not contradict annotations; adds context that is not in 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is relatively long but every sentence adds value: core purpose, plan gating, defaults, pagination details, sibling distinction. It is well-structured with front-loaded purpose and subsequent behavioral details. No wasted words given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, 100% schema coverage, no output schema, the description covers key behavioral aspects: caching, error handling, pagination, plan restrictions, and sibling differentiation. It lacks explicit return value structure but lists returned fields in the first sentence, which is sufficient for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 9 parameters. The description adds meaning beyond schema: default limit behavior, cursor staleness reset, fields whitelist as array, supported filter keys, refresh cache bypass, verbose mode, and optional filter queries. This enriches parameter understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns 'instance-wide configuration audit logs as paginated skeletons' with specific fields listed. It distinguishes itself from the sibling tool 'get_ticket_audits' by specifying that this tool is for admin-config changes only, not ticket-level changes, making purpose and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use the alternative 'get_ticket_audits' for ticket-level changes. Details plan-gating behavior (Enterprise only, returns error on lower plans) and default limit. Provides clear context for pagination and filter usage, guiding the agent 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral details beyond annotations: pagination mechanics, caching, plan-gating requiring Enterprise, degradation to upstream_error on lower plans, and cursor staleness behavior. This all enriches 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the core action, efficiently packed with essential details. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (pagination, caching, plan-gating, multiple options), the description covers all critical behavioral aspects. Without an output schema, it describes the default projection and verbose alternative, ensuring the agent knows what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have schema descriptions (100% coverage). The description adds context for limit default and verbose, but the schema already documents each parameter adequately. Hence the description adds moderate additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns custom agent roles as paginated skeletons, listing the default fields (id, name, team_member_count, updated_at). It distinguishes from system roles, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains default limit, cursor pagination, and options like verbose. It notes the distinction from system roles but does not explicitly contrast with the sibling get_custom_role. Still, the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds important behavioral details beyond annotations: plan-gating (Professional+, degrades to 'upstream_error'), cursor auto-reset on stale cursors, and server-side caching. Annotations declare readOnlyHint, openWorldHint, idempotentHint, which are consistent with 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at 4 sentences, front-loaded with the core purpose and behavior. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the return structure for both thin and verbose modes, cursor and error behavior, and ties to other tools (list_locales). It is comprehensive for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The tool description provides a high-level summary of parameters (defaults, usage patterns) but adds no new semantic details beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Returns dynamic content items' with a specific verb and resource, explaining what dynamic content is (localizable snippets) and the output format (paginated skeletons with specific fields). This distinguishes it from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use (e.g., passing 'verbose: true' for full objects) and cross-referencing with 'list_locales'. However, it does not explicitly contrast with alternatives like 'get_dynamic_content' or state 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations (readOnlyHint, etc.) by detailing caching behavior ('full corpus fetched and cached server-side'), cursor invalidation, and default limit. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Reasonably concise with front-loaded purpose. Some parameter details overlap with schema, but overall structure is clear and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations cover safety, schema covers parameters, and description adds caching, cursor, and return format details. No output schema, but return is adequately described. Sibling context enriches understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context like how limit interacts with caching, cursor staleness behavior, and filter supported keys, providing value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Returns locales enabled on the instance as paginated skeletons' with specific fields, and distinguishes from siblings by noting its use for validating default_locale_id. The verb and resource are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use to discover which default_locale_id values are valid for list_dynamic_content variants', providing a clear use case. However, it doesn't mention when not to use or name alternatives, though sibling list is provided.
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, openWorldHint, and idempotentHint, indicating safe read behavior. The description adds valuable behavioral details: pagination with caching, default limit 100, cursor staleness auto-reset, filter ignoring unsupported keys, and projection via fields/verbose. This goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first sentence clearly states purpose and key defaults, second sentence provides alternative tools. No wasted words, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, but high schema coverage, the description covers pagination, caching, projection, filtering, and links to sibling tools for safety and hygiene. It is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds contextual meaning beyond schema: default limit, cursor being opaque token from previous response, filter supported keys listed, and verbose for full objects. It also explains cache behavior and refresh parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns ticket fields as paginated skeletons with specific fields, and distinguishes from sibling tools by referencing find_field_usage and audit_field_health for different purposes. The verb 'returns' and resource 'ticket fields' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides alternatives for related tasks: 'For is it safe to delete this field? call find_field_usage' and 'For a full field hygiene report, audit_field_health'. It implies when to use this tool (listing fields) and when to use others, though it does not state explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint. Description adds operational detail: 'Operates over the cached verbose corpus, no extra HTTP'. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no waste. First sentence states purpose and output, second gives usage context, third explains operation and alternative. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description provides clear purpose, usage guidelines, operational details, and mentions output structure. Lacks details on pagination or limits but is sufficient given annotations and schema completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions; description adds no additional param info beyond schema. Schema coverage is 100%, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'find', resource 'ticket form references', and scope across multiple entities (triggers, automations, macros, views). It distinguishes from sibling tools like find_field_usage and audit_field_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('is it safe to retire this form?') and when to use alternative ('audit_field_health for broader form hygiene').
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 safe, idempotent, read-only. Description adds caching behavior (operates over cached corpus, no HTTP unless refresh:true) and return format (references with why_matched breadcrumbs), providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus bolded use-case and sibling contrast. No wasted words, well-structured with action, return format, usage guidance, and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format, caching, use case, and alternative tool. Without output schema, description provides enough context for effective use. Could mention that references contain entity type/ID but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. Description adds meaning to 'refresh' by explaining it bypasses cache, which is helpful context beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Find every reference to an agent group across triggers, automations, views, and SLA policies' with specific verb+resource+scope, and distinguishes from sibling 'audit_trigger_health' by noting it checks orphans including dangling group ids.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly calls out 'The right tool for "is it safe to delete this group?"' and contrasts with 'audit_trigger_health' for broader orphan detection, providing clear when-to-use and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral context: it fetches one target with full body and is meant for legacy targets, which goes beyond the annotations and aids agent understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, first stating the function, second providing usage guidance. No wasted words, front-loaded effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple fetch tool: it identifies the operation, scope (legacy), and response nature (full body). It differentiates from many sibling get_* tools. Lacking output schema is acceptable given the context, but a slight gap is the absence of note about parameters or response structure beyond 'full body'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (id and instance both described). The description does not add new information about parameters but aligns with the schema. Baseline 3 is appropriate as schema adequately handles semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one legacy target by ID with full body', specifying the verb (fetch), resource (target), and distinguishing scope (legacy). It explicitly contrasts with get_webhook for new integrations, making purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'For new integrations prefer get_webhook' and implies this tool is for legacy targets. This clearly tells when to use and when not to, with a specific alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds crucial details: defaults to limit:100, event_types filtering, scope-gated behavior with auto-redaction of comment bodies, and via.source attribution. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph with front-loaded purpose, then defaults, filtering, scope, use case, and alternative. Every sentence adds value; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complex tool with 10 params and no output schema. Description covers core behavior, use case, permissions, and parameter usage. Lacks explanation of cursor pagination and filter object, but overall sufficient for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 70%. Description adds meaning for limit (defaults to 100), since (bound by date), and event_types (skip Comment events). Also implies verbose returns full objects. Compensates for undocumented parameters like cursor and filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it returns audit history for a ticket with state changes, rule attribution, and timestamps. Clearly distinguishes from sibling get_ticket_metrics by noting different use cases. Specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use this for forensic debugging' with example question, and notes alternative 'For pure timing data, get_ticket_metrics is cheaper'. Also mentions scope requirements and filtering options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, openWorldHint, idempotentHint. Description adds plan-gated degradation to upstream_error envelope, scope-gating, caching behavior with cursor staleness, and pagination details, all beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus succinct details. Front-loaded with main purpose, then constraints and usage. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers plan-gating, scope-gating, and usage alternative. However, without output schema, the description could describe the return format (what skeleton fields are included) for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description does not add extra parameter meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists side conversations attached to a ticket as paginated skeletons, distinguishing from get_ticket_comments for the main public conversation. Specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (surface parallel email/Slack thread) and when not (use get_ticket_comments for main conversation). Also mentions plan-gating and scope-gating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, but the description adds context about operating over a cached corpus with optional refresh, and details the output structure. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured. Front-loads purpose, uses bold for emphasis, and each sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains return fields (kind, id, title, mode, set_only) and mentions near-duplicates. Covers caching behavior. Could explicitly state it returns a list, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds meaning to the parameters: explains that refresh bypasses cache and instance overrides sticky instance, providing beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inventories every tag referenced across triggers, automations, and macros, with specific output details (where-used rows, near-duplicates, set_only flag). It distinguishes from siblings like audit_tag_sprawl and find_triggers_by_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use and when-not-to-use guidance: directs to audit_tag_sprawl for full audit and find_triggers_by_tag for specific tag lookup. Also notes that it uses a cached corpus and only makes HTTP calls if refresh is true.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses significant behavioral traits beyond annotations: pagination with cursor and caching, default limit, filter supported keys, ability to bypass cache with refresh, and behavior of stale cursors. Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and the description adds rich context without any contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences. The main purpose is front-loaded in the first sentence. Every sentence serves a purpose: main action, parameter/usage hints, and alternatives. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, the description covers return format (skeletons), default limit, caching, cursor handling, and filter keys. However, it does not describe the pagination response structure (e.g., how to get next page) or the full view object format in verbose mode, which are minor gaps. Still, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds usage patterns like using fields to opt into extra fields without going fully verbose and lists supported filter keys. This provides additional context beyond the schema, justifying a score above baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns views as paginated skeletons, listing specific fields. It also distinguishes from sibling tools by explicitly directing users to find_unused for unused views and find_field_usage etc. for impact analysis. The verb 'returns' and resource 'views' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use alternative tools (find_unused for unused views, find_field_usage for impact analysis). However, it does not explicitly state when list_views should be chosen over other listing tools, though the context implies general listing of views. No exclusions or when-not-to-use are given.
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 (readOnlyHint, idempotentHint, openWorldHint) already disclose safety and idempotency. Description adds beyond that: return type is 'mixed-type results in their native shape' and mentions scope-gating, which clarifies result shape and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. The key information (verb, resource, usage guidance) is front-loaded. Every sentence adds necessary context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return format ('mixed-type results in native shape') and mentions scope-gating. Missing details on pagination or error handling, but acceptable given tool complexity. Leaves agent informed about result shape and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 5 parameters. Description adds value by providing concrete query syntax examples (e.g., 'type:ticket status:open'), which goes beyond schema descriptions. No contradictory info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a Zendesk v2 Search query across tickets, users, organizations, and groups, returning mixed-type results. It distinguishes itself from siblings like list_tickets by emphasizing its cross-resource search capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this before list_tickets/list_users/list_organizations for specific records, calling out the search index as faster than enumeration. Also mentions scope-gating behavior, providing concrete when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable context (scope-gating, blocked response, inline data structure) without contradiction, but could still be more detailed about exact response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with core purpose, then details options and guidance. Every sentence is informative with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description covers inline includes, scope-gating, and blocked response. Could explicitly state primary return object is the ticket, but context is sufficient for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% with parameter descriptions; description adds why include_comments/audits save round-trips and explains verbose affects projections, enriching beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Fetch one ticket by ID' and mentions optional inline includes for comments/audits, distinguishing it from sibling tools like get_ticket_comments, get_ticket_audits, and get_ticket_metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use inline includes (saves round-trips) and when to use get_ticket_metrics for SLA data, plus mentions scope-gating and blocked calls, providing clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations by noting scope-gating and full profile details, while annotations already declare readOnly, openWorld, and idempotent hints. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose, followed by scope and alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with good annotation coverage; description covers scope and alternative. No output schema needed as return value is implied. Fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description reinforces 'by ID' but does not add significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Fetch one user by ID with full profile details', using a specific verb and resource, and distinguishes from sibling tools like 'search' for email lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions scope-gating and directs to use 'search' with 'type:user' for alternative lookups, providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds useful context: paginated skeletons, plan-gated behavior (upstream_error), scope-gated, cache/cursor behavior. No contradictions. A 4 is appropriate as it adds significant 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Approximately 4 sentences, front-loaded with purpose, then API backing, constraints, and alternatives. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, API endpoint, plan/scope gating, pagination, caching, parameter behaviors, and alternatives. Could mention response shape slightly more, but overall very complete for a list tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. Description adds substantial meaning for many parameters: explains limit scoping, cursor staleness, field whitelisting, filter options, cache bypass, etc. Greatly enhances agent understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (returns) and resource (routing-attribute values an agent holds) and explicitly distinguishes from sibling tools list_routing_attributes and list_routing_attribute_values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (for agent assignments) and when not to (for catalogs), provides alternatives, and mentions plan/scope gating constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent; description adds context about sticky markers and default instance, offering 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words, front-loaded with action and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with no params or output schema; description fully covers what it does, when to use it, and how to proceed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage 100%; baseline score of 4 per guidelines for 0-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists every Zendesk instance with markers, which distinguishes it from siblings like current_instance and set_instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: call at session start, then use set_instance; also provides cross-instance comparison strategy.
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, openWorldHint, idempotentHint. Description adds details on pagination (default limit=100, cursor behavior, caching), plan-gating, and degrades to upstream_error. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, uses bullet points effectively, front-loads the main purpose. Every sentence is informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return format (skeletons) and options to get full objects (verbose). Covers plan-gating, pagination, and error scenarios. Complete for a list tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds valuable context for each parameter (e.g., limit explains caching, cursor explains staleness, fields whitelist, filter supported keys, refresh bypasses cache). This goes beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns skill-based-routing attribute definitions as paginated skeletons. It specifies the fields (id, name, updated_at) and distinguishes from sibling tools list_routing_attribute_values and list_skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (for attribute definitions), when not (for values inside an attribute, use list_routing_attribute_values; for legacy skills, use list_skills). Also mentions plan-gating and potential error 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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds specifics: pagination, caching, plan requirement, and parameter behavior beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured. Front-loads core purpose, uses bullet-like formatting, every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return format (skeletons), how to get full objects (verbose), pagination, and plan requirement. Covers all key aspects for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. Description adds context like cursor staleness, filter supported keys, and default limit, going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns SLA policies as paginated skeletons with specific fields (id, title, position, updated_at). It differentiates from sibling tool get_sla_policy (individual) and find_group_usage (scan for group usage).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this vs alternative: 'For "which SLA fires on group X?" call find_group_usage'. Also mentions plan gating (Professional+).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, openWorldHint, idempotentHint. The description adds significant behavioral context: pagination via cursor and limit, caching behavior (server-side cache, stale cursor auto-reset), default projection, optional fields parameter, filter capabilities, and refresh option. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with core functionality and a bolded usage tip. Every clause adds value: no filler. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return shape (skeletons with specific fields), pagination, caching, filtering, projection options, and typical list size. It covers all essential aspects for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: e.g., 'Default limit: 100', cursor caching details, filter supported keys, and the effect of verbose vs. fields. This enriches understanding of parameters without repeating schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns ticket forms as paginated skeletons with a specific projection (id, name, active, etc.). It distinguishes from the sibling tool 'find_form_usage' by its use case: enumeration vs. safety checking. The verb 'Returns' and resource 'ticket forms' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool vs. the alternative: 'For "is it safe to retire this form?" call find_form_usage'. It also notes that 'straight enumeration is usually fine' due to small form lists. However, it could be clearer about when not to use this tool (e.g., if you need full details without verbose).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by describing pagination with cursor behavior, caching, default limit, and the refresh parameter. No contradiction with readOnlyHint, openWorldHint, or idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a succinct note. Front-loaded with purpose, followed by usage guidance. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a listing tool with 7 parameters and no output schema. Covers return projection, pagination, caching, filtering, and alternatives. Adequate in context of rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds little beyond summarizing available parameters, which is sufficient but not extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns trigger categories as paginated skeletons, with specific fields. Distinguishes from sibling tools by directing to audit_trigger_health for missing categories and list_triggers for triggers in a category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use alternatives: audit_trigger_health for missing categories, list_triggers with category_id filter for triggers in one category. Also implies default limit and parameter usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and idempotent hints. The description adds valuable behavioral details: default limit of 100, server-side caching, cursor pagination with stale cursor handling, filter application to cached corpus, and ignored unsupported filter keys. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement followed by parameter behavior and sibling references. Every sentence adds value, though it is slightly longer than necessary but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers return structure, pagination, filtering, caching, and all 7 parameters. Given the complexity and richness of the schema, it fully equips 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3, but the description significantly enhances each parameter: explains limit default and caching, cursor behavior (stale cursors auto-reset), fields whitelist usage, filter supported keys, refresh bypasses cache, and instance override. Adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns webhooks as paginated skeletons, listing the specific fields (id, name, status, endpoint, updated_at). It distinguishes itself from sibling tools like list_webhook_invocations and list_targets, which are explicitly mentioned for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs. alternatives: for per-webhook delivery history, use list_webhook_invocations; for legacy targets, list_targets. It does not state explicit when-not-to-use scenarios but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe read. Description adds that it's a 'cheap sanity check,' implying low cost, and specifies the behavior when no instance is set (returns null). This provides extra context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, then usage guidance. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description fully covers the return value, usage context, and cheap nature. Annotations cover safety. Complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds no parameter info because none is needed. With no parameters, the dimension is effectively satisfied, and there is no omission.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the currently active sticky instance or null. It uses specific verb+resource (returns instance) and distinguishes from siblings like set_instance (which sets) and list_instances (lists all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance: 'call this when you're unsure whether `set_instance` has been run yet.' This gives clear context for when to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds caching behavior ('operates over the cached verbose corpus, no extra HTTP unless refresh: true') and return structure. Good but doesn't explain potential side effects of refresh, though minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action, uses bold for emphasis, and each sentence adds necessary info without redundancy. Concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description adequately explains return values. All parameters are covered, caching behavior is described, and usage context is given. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds valuable context beyond schema: for field_id, 'The numeric portion is what gets matched'; for refresh, 'Bypass cache and re-fetch'; for instance, 'Override the sticky instance for this call'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds every reference to a custom ticket field across multiple entity types (triggers, automations, etc.), specifies return format ('references' with 'why_matched' and 'reference_count'), and explicitly distinguishes from sibling 'audit_field_health'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the use case: 'The right tool for "is it safe to delete this field?"' and advises when to use an alternative: 'For a full field-hygiene report ... use audit_field_health instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses cached operation ('over the cached verbose corpus with no extra HTTP'), result details ('why_matched breadcrumb'), and scope modes. Annotations already declare readOnly, openWorld, idempotent; description adds meaningful context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver purpose, output details, and usage guidance without wasted words. Structure is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description notes the important 'why_matched' field. It covers caching behavior, alternative tools, and mode scoping. The only minor gap is not explicitly stating exact tag matching (schema says it, but description relies on that).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already described. The description adds context for the 'mode' parameter by explaining each enum value in relation to the tool's purpose, and mentions the 'refresh' parameter impacts caching. This enhances understanding beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Find triggers that reference a specific tag', clearly stating the verb and resource. It distinguishes from siblings by recommending list_triggers, list_tags_in_use, and audit_tag_sprawl for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Always reach for this before list_triggers + manual scan', and directs to list_tags_in_use for broad tag discovery and audit_tag_sprawl for hygiene audits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint), the description explains data source (usage_30d stats), that it only returns confident verdicts, and why triggers/automations are unsupported. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with main purpose, then caveats, then alternatives. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description hints at return format ('confident verdicts', 'indeterminate'). Could be more specific about output structure, but acceptable for a simple tool. Covers main behavior and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. Description adds value by explaining the behavior for specific enum values (triggers/automations always return indeterminate), beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it detects unused macros and views by reading usage_30d stats. It distinguishes from siblings by specifying it cannot handle triggers/automations and suggests alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when-not to use: triggers and automations always return indeterminate. Provides specific alternative tools for trigger/automation cleanup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: paginated skeletons, default limit, caching behavior, cursor auto-reset, filter keys, and verbose option. Annotations already declare readOnlyHint, openWorldHint, idempotentHint; description 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured: main purpose first, then options, then alternative tools. Each sentence adds value, though could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description effectively explains return format (skeletons, verbose option). Covers pagination, caching, filtering, and refresh. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining defaults (limit 100), caching semantics, cursor staleness behavior, and filter keys. This goes beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Returns macros as paginated skeletons' and specifies default fields. It differentiates from sibling tools by noting when to use find_unused or find_field_usage for specific queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use this tool vs alternatives: 'For which macros are unused? call find_unused... For tag/field impact... use find_field_usage or audit_tag_sprawl.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: pagination, default limit, caching behavior, scope-gating, expensive enumeration warning. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose, then defaults, then alternatives. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Explains return shape (skeletons with fields, verbose for full objects), pagination behavior, and filter capabilities. Lacks explicit pagination response structure but compensates with cursor details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions; description adds extra nuances (e.g., limit only controls response, filter unsupported keys ignored, stale cursor reset).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Returns organizations as paginated skeletons' with specific fields, distinguishes from search and list_organization_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (enumeration) and when not to (prefer search for specific org), mentions scope requirements and lists alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses pagination behavior (default limit, cursor, cache), scope gating, and caching details. Annotations already provide readOnlyHint, openWorldHint, idempotentHint; description adds valuable context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured paragraph that front-loads the main purpose and then provides essential details. Every sentence adds value, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description comprehensively covers return format (fields, projection), pagination (cursor, limit), caching, scope restrictions, and alternatives. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds significant meaning: explains cursor staleness, filter supported keys (active, category_id, title_contains, updated_since), verbose vs thin projection, and caching behavior. Goes well beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states that the tool returns paginated user skeletons with specific fields. Differentiates itself from sibling tools like 'search' (for finding specific users) and 'list_agent_skill_assignments' (for skill values).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use 'search' instead of full enumeration, and states scope requirements ('config_plus_audits' or 'full', with 'config' returning 'scope_blocked'). Provides clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotence; description adds that it tolerates per-kind errors and lists failures in notes, which is valuable beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences pack significant information but could be slightly more structured. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description fully explains return value (counts, metrics, notes on failures). Sufficient for a dashboard tool with complex composition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description clarifies caching behavior tied to 'refresh' parameter, adding context not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a one-call dashboard providing counts of every config object and headline metrics. Distinct from sibling audit/list tools by being a composite summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends running this first for new client engagements to prime cache and make subsequent calls free. Provides actionable timing advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and idempotent hints. Description adds rich behavioral details: pagination with cursor, caching, filtering, refresh, verbose, parameter behavior beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences: defines core, gives defaults/options, contextualizes size, provides alternative. No wasted words, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description covers return format (skeletons or full objects), pagination, caching, filtering, refresh, and verbose. Complete for a read-only listing tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context: limit only limits response, cursor behavior, fields usage, filter supported keys, refresh and verbose. Adds value above schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns custom ticket statuses as paginated skeletons, specifying the default fields. Distinguishes from siblings by noting alternative for deep hygiene checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: for simple listing, enumeration is fine; for deeper hygiene checks, use find_triggers_by_field with field 'status'. Provides clear when-to-use and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, openWorldHint. The description adds valuable context: paginated skeletons with default limit 100, ability to pass cursor/fields/filter/verbose, caching behavior (cursor staleness), and the plan-gating. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first explains core behavior, second provides usage guidance vs. sibling. No fluff, every sentence earns its place. Front-loaded with most important info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and sibling context, the description is complete. It explains return shape (skeleton with specific fields), pagination with cursor, and filtering options. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: explains 'verbose' returns full schedule objects with intervals, 'fields' opt-in without full verbose, and 'filter' supported keys. This enriches understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns business-hours schedules as paginated skeletons with specific fields (id, name, time_zone, updated_at). It distinguishes from the sibling tool `list_business_hours` by explaining that tool composes intervals and holidays, which the list alone doesn't cover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs. `list_business_hours`: 'For "what are the actual business hours?" call list_business_hours with a schedule_id, it composes intervals + holidays, which the schedule list alone doesn't cover.' Also mentions it is plan-gated (Professional+).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes pagination, cursor invalidation, caching, filter behavior (unsupported keys ignored with note). Annotations already indicate read-only and idempotent, and description adds valuable behavioral context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first explains purpose and output, second provides usage details and sibling distinction. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, but description covers pagination, caching, filtering, and sibling differentiation comprehensively. Agent has enough to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions. Description adds practical context like default limit, cursor auto-reset, filter behavior, and verbose mode, providing additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns user-level custom fields schema as paginated skeletons with specific fields, and explicitly distinguishes from list_ticket_fields and list_organization_fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides default limit, cursor behavior, filtering options, and explicitly states when to use get_user for values instead. Clearly differentiates from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond idempotentHint annotation, description reveals that omitting 'kinds' drops the HTTP client, enabling config file changes. Also notes idempotency and no destruction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load purpose, then detail scope and alternatives. Every sentence adds value with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a cache invalidation tool with two optional parameters and no output schema, the description covers behavior, side effects, and alternatives completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions, but the description adds contextual examples and explanation of default behavior (omitting kinds wipes all, instance defaults to sticky).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Invalidate' and the resource 'in-memory cache for an instance', with scoping via 'kinds'. It is distinct from sibling tools which are get/list/audit operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call after user changes in Zendesk admin UI, and contrasts with one-off 'refresh: true' on other tools. Provides clear when-to-use and alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, and idempotentHint, which are consistent. The description adds behavioral details: caching of full corpus, cursor auto-reset on staleness, filter behavior for unsupported keys, and scope-gating. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with no wasted sentences. It front-loads the core purpose and then adds key details in a structured manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no output schema, the description covers return format, pagination, caching, filter, and alternative tool. It provides enough context for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema description coverage, the tool description adds significant value: explains 'verbose' effect, gives example for 'fields', lists supported filter keys, and describes cursor behavior. This goes beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifically states 'Return the comment thread for one ticket as paginated skeletons' and lists the fields returned. It also distinguishes from the sibling tool get_ticket_audits, making the purpose clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: mentions passing 'verbose: true' for additional data, and directs users to get_ticket_audits for change attribution. It also notes the scope-gating requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses scope-gating, caching behavior, pagination via cursor with stale cursor handling, filter key restrictions, and refresh option. Adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main output, then parameter options, scope warning, and usage advice. Dense yet clear; every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description covers return formats (skeletons vs full), all parameters, caching, pagination, filtering, and alternatives. Comprehensive for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds meaning to each parameter: explains default limit, cursor behavior, supported filter keys, refresh bypass, and verbose full bodies. Goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns tickets as paginated skeletons with specific fields. Distinguishes from siblings like search and get_ticket with explicit usage guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use alternatives: 'For specific lookups prefer search' and 'For a single ticket's context use get_ticket'. Also explains scope restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds significant behavioral context: pagination mechanics (default limit, cursor auto-reset), cache behavior (cold cache slow, subsequent near-instant), projection options (fields, verbose), and filter behavior (ignored unsupported keys with note). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured paragraphs with front-loaded key information. Every sentence earns its place, covering purpose, parameters, performance, and alternatives without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains response shape (paginated skeletons vs. full bodies). Covers pagination, filtering, caching, and alternative tools. Complete for a list tool given its complexity and rich annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters described). The description adds meaning beyond schema: default limit value, cursor stale behavior, filter supported keys, fields whitelist concept, verbose flag effect. Adds substantial value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns triggers as paginated skeletons with specific fields ('id', 'title', 'active', 'updated_at'). It distinguishes from sibling tools like find_triggers_by_tag and find_triggers_by_field by specifying their different use cases ('which triggers do X?').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides when to use this tool vs. alternatives: for 'which triggers do X?' questions it recommends finders. Also provides performance guidance: without filter on large instances it can be slow on first call due to cold cache.
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:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rlowndes9/zendesk-mcp-server'

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