x-mcp
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation3/5
Most x_api_* tools target distinct resource actions, but overlapping families exist (e.g., account_activity_subscription vs activity_subscription, get_users_timeline vs get_users_posts, reposted_by vs reposts) that could cause misselection. Descriptions help differentiate, but the sheer volume of similarly named tools makes boundaries less clear.
Naming Consistency4/5The dominant pattern is x_api_<verb>_<resource> and is applied consistently across the huge endpoint set. Minor deviations exist: 'remove' vs 'delete', 'add' vs 'create', and unofficial core tools use x_config_*/x_auth_* prefixes, but the pattern is still readable and predictable.
Tool Count1/5With 179 tools, this is an extreme count far beyond the calibration guidance for well-scoped servers. The server appears to be a raw auto-generated wrapper around the entire X API, which overwhelms agents and makes discovery and selection impractical.
Completeness5/5The tool surface is remarkably comprehensive, covering CRUD and lifecycle operations for posts, users, lists, DMs, media, spaces, trends, compliance, webhooks, activities, articles, community notes, and insights. Core auth/config utilities plus a generic x_api_request fallback ensure no obvious dead ends exist.
Average 4/5 across 179 of 179 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Read', which implies non-destructive, but it doesn't state whether the tool requires specific credentials, what happens if the key is not found, or whether it returns null or errors. No behavioral traits beyond the basic read operation are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, achieving high conciseness. However, it is so minimal that it sacrifices usefulness; while every word is purposeful, the description lacks necessary elaboration on parameters and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, no output schema, and a set of closely related config tools, this description is severely incomplete. It doesn't explain the parameters, when to use it vs. x_config_list, or what the response contains. The tool cannot be effectively invoked based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 4 parameters (key, scopeUserId, scopeTenantId, scopeAccountId) with zero schema descriptions. The description mentions 'tenant/principal' but does not explain that scopeUserId, scopeTenantId, and scopeAccountId are the scoping inputs, nor what 'key' refers to. It provides no meaning beyond what the field names already suggest, so it fails to compensate for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a single Postgres configuration value scoped to a tenant/principal. The verb 'Read' and resource 'configuration value' make the primary action clear, and it's distinct from x_config_list (which lists) and x_config_set (which writes). However, it doesn't explicitly differentiate from x_config_list or mention that multiple scope parameters exist, so it falls short of the highest clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to use this tool versus x_config_list or x_config_set, nor does it mention any prerequisites or exclusions. The name and description imply a single-value lookup, but nothing explicit guides the agent on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and provides substantial behavior: 'Risk: mutating, high-risk,' required OAuth scopes, environment-selection behavior, common failure conditions, and a safety warning to validate before use. It does not fully explain the upload state mutation, but it is far beyond minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections and includes an example, making it scannable. However, it repeats risk/safety warnings and includes the tautological 'Use when: Append Media upload,' so not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It provides expected response shape, failure conditions, permissions, and safety warnings, which is helpful given no output schema or annotations. Yet the core media-upload workflow is missing: what id refers to, how body/multipartForm should be structured, and how append relates to initialize/finalize.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, but it only vaguely covers id and body and explains auth-related scope/credential parameters. multipartForm and preferredAuthType are never mentioned, and body's structure is not specified beyond 'documented request payload.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Append Media upload,' which largely restates the tool name without explaining the action in context. It fails to define what 'append' means (e.g., uploading a chunk to an existing media upload) or distinguish this from x_api_initialize_media_upload, x_api_finalize_media_upload, or x_api_chat_media_upload_append.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line is tautological ('Append Media upload'), and the 'Do not use when' only warns against exploratory use, suggesting x_schema_discovery or x_query_suggestion. It provides no guidance on choosing this over closely related media-upload sibling tools or sequencing after initialize/finalize.
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?
Despite no annotations, the description extensively discloses permissions (OAuth scopes), auth-resolution behavior, expected response shape, common failures, and safety warnings. It clearly states 'Risk: read-only' and warns about sensitive data, exceeding baseline transparency. However, it doesn't explain the payload contents or pagination details, so a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections (Risk, Required permissions, Expected response, etc.) and an example. The only waste is the redundant 'Use when: Get muting' line, but overall it's organized and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters, no annotations, and no output schema, yet the description omits the core semantics: what exactly is being retrieved and what fields the response contains. It provides operational details like failures and auth, but without a clear definition of 'muting', the agent cannot determine if this tool fits the user's request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only partially compensates. It lists id, max_results, and pagination_token with minimal types, and explains the scopeTenantId/scopeUserId/scopeAccountId/credentialKey interplay in prose. However, it omits authorizationKey and preferredAuthType, and fails to describe what 'id' represents (the user whose muting list is being fetched).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get muting', which merely restates the tool name without specifying the resource or action clearly. It does not mention that this retrieves a list of users muted by the authenticated user, making it indistinguishable from sibling tools like x_api_get_users_blocking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: Get muting' is tautological and provides no decision context. The 'Do not use when' clause only covers exploration and prerequisite scenarios, not when to prefer alternative muting-related tools. It offers no guidance on when this tool is the right choice versus x_api_mute_user or x_api_unmute_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?
No annotations are provided, so the description carries the full burden. It clearly discloses read-only risk, required OAuth scopes and token types, environment-selection behavior involving scopeTenantId/scopeUserId/scopeAccountId, expected response shape, and common failure conditions. It also adds a safety warning about sensitive data, which is valuable beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it easy to scan. However, the opening lines are redundant: 'Get DM events.' followed by 'Use when: Get DM events.' wastes space. Several sections are concise, but the redundancy prevents a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite covering auth, response shape, failures, and example, the description omits the crucial distinction from sibling DM event tools—it never states whether this returns all events, events for a specific conversation, or events for a participant. This ambiguity is a major gap for correct tool selection, and pagination behavior is also not fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining auth-related parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) and the environment-selection rule. It lists types for max_results, pagination_token, and event_types, but does not explain the semantics of event_types or pagination_token, and omits authorizationKey and preferredAuthType entirely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description simply says 'Get DM events,' which restates the tool name without adding specificity. It fails to distinguish this from sibling tools like x_api_get_direct_messages_events_by_conversation_id or x_api_get_direct_messages_events_by_participant_id, leaving the exact scope (all events vs. per conversation/participant) unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: Get DM events' is tautological and provides no actionable selection criteria. The 'Do not use when' section only mentions preferring x_schema_discovery or x_query_suggestion for exploration and auth/config tools, but offers no guidance on choosing among the multiple DM event 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?
With no annotations, the description carries the full burden and does well. It discloses read-only risk, bearer token prerequisites, detailed environment-selection behavior (scopeTenantId plus exactly one of scopeUserId/scopeAccountId), credentialKey override, expected response shape, common failure conditions, and safety warnings about sensitive data. This exceeds the structured schema and provides rich operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections (Risk, Required permissions, Environment-selection behavior, etc.) which aids scanning. However, the opening 'Activity Stream.' and 'Use when: Activity Stream.' are redundant filler. The rest is informative and not overly verbose, but the tautological parts detract.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no output schema and no annotations, the description provides valuable context: response shape, failure modes, prerequisites, and an example. Yet it fails to clearly explain what the activity stream represents or what data the agent will receive, and leaves several parameters undocumented. This prevents the description from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the role of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in auth resolution, and lists types for backfill_minutes, start_time, and end_time. However, authorizationKey and preferredAuthType are completely unaddressed, and the time parameters lack semantic detail (e.g., format, meaning). Partial compensation with clear gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Activity Stream.' and 'Use when: Activity Stream.' which merely restates the tool name without a verb or resource. It fails to specify what the tool actually does (e.g., retrieves, lists, streams activity events). This is essentially a tautology and provides no distinguishing information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: Activity Stream' offers no actionable guidance. The 'Do not use when' clause mentions preferring x_schema_discovery or x_query_suggestion when exploring, but does not clearly define the positive use case or contrast with similar x_api_* tools. Recommended tools are listed but without explicit when-to-use criteria.
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?
With no annotations, the description provides extensive behavioral context: it declares 'Risk: read-only', lists required OAuth scopes and token types, explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId and credentialKey, describes the expected response shape, common failure conditions, and safety warnings. This far exceeds the minimal expectation and helps the agent understand side effects, auth requirements, and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organized with labeled sections, but it is longer than necessary. The opening 'Get blocking' and 'Use when: Get blocking' are redundant, and some sections could be tightened. Despite this, most sentences convey useful information, so it is not overly verbose, but it does not achieve the zero-waste conciseness of top-tier examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides strong operational details: permissions, response shape, failure conditions, and safety warnings, which is valuable given no output schema and no annotations. However, it lacks a precise statement of what the tool actually returns (e.g., 'a list of users blocked by the authenticated user'), and it fails to explain several parameters, leaving gaps in an agent's ability to fully understand constraints and usage. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'Parameter formats and constraints' section adds meaning for id (path, required), max_results (query, integer), and pagination_token (query), which is useful but covers only 3 of 9 parameters. The environment-selection behavior partly explains scopeUserId, scopeAccountId, and credentialKey, but authorizationKey and preferredAuthType remain unexplained. Given the 0% schema description coverage, the description partially compensates but leaves several parameters opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get blocking.' which merely restates the tool name and provides no details about what is being blocked, by whom, or in what context. It does not articulate a clear verb+resource+scope (e.g., 'List users blocked by a specified user ID') and fails to distinguish from sibling tools like x_api_get_users_muting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when:' section is empty of actual guidance, repeating 'Get blocking' without context. The 'Do not use when:' section gives generic advice to prefer schema discovery or query suggestion for exploration, but it does not offer positive use cases or differentiate from similar user-list tools such as followers, muting, or following. This is insufficient for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are present, the description compensates by detailing risk (read-only), required auth scopes, environment-selection behavior for tenant principal resolution, common failure conditions, and safety warnings. This goes well beyond a minimal disclosure and gives an agent a clear picture of what to expect and what could go wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Use when, Risk, Required permissions, etc.), making it easy to scan. It is somewhat long but each section carries useful information, and the example adds practical value. It is concise relative to the amount of context it packs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers many operational aspects: permissions, environment selection, response shape, failure conditions, and an example. However, it lacks a clear explanation of what 'mentions' means in this API context and does not define the semantics of key query parameters. For a tool with 13 parameters and no annotations, this is a noticeable gap, though the overall coverage is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameters with their locations (path/query) and types, and explains how scopeTenantId, scopeUserId, scopeAccountId, and credentialKey interact for auth resolution. However, many fields like since_id, until_id, pagination_token, and start_time/end_time are marked as 'unknown' or just 'string' without explaining their purpose or format. Given the schema has 0% description coverage, the description only partially fills the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description says only 'Get mentions,' which is essentially a restatement of the tool name and lacks specificity. It does not clarify whose mentions are retrieved (e.g., mentions about a user) or distinguish this from sibling tools like x_api_get_users_timeline or x_api_get_users_posts. The purpose is therefore vague and under-specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' is tautological ('Get mentions') and provides no practical decision guidance. The 'Do not use when' gives generic advice about preferring schema discovery or query suggestion for exploration, but it does not differentiate this tool from other user-related X API tools. No concrete alternatives are named for the specific task of fetching 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?
No annotations are provided, so the description carries the full burden. It explicitly states the tool is read-only, requires a bearer token, explains environment-selection behavior for scoped credentials, provides an expected response shape, lists common failure conditions, and includes a safety warning about sensitive data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and an example. However, the opening 'Use when: Get webhook' is a redundant tautology, and some sections contain generic boilerplate that could apply to any x_api_* tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides strong operational context: response shape, failure conditions, auth, and an example. However, it fails to explain what a webhook is, whether the response contains a single webhook or a list, or what domain-specific fields the data will include. Since there is no output schema, this missing semantic detail leaves a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description meaningfully compensates by explaining that scopeTenantId plus exactly one of scopeUserId or scopeAccountId selects the tenant principal, and that credentialKey selects a non-default credential profile. It also notes there are no endpoint-specific parameters, though it leaves authorizationKey and preferredAuthType implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get webhook,' which simply restates the tool name and provides no additional meaning. It does not specify whether this retrieves a single webhook or lists all webhooks, nor does it distinguish itself from sibling webhook tools like x_api_get_webhooks_stream_links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is circular ('Get webhook') and gives no practical guidance. The 'Do not use when' condition is generic—applying to exploration or auth prerequisites—rather than explaining when to choose a sibling tool or an alternative for webhook retrieval.
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?
With no annotations, the description takes on the safety transparency burden. It explicitly states 'Risk: read-only,' required OAuth scopes, environment-selection behavior, common failure conditions, and an expected response shape. It also warns that read-only responses can contain sensitive account data. This is strong behavioral disclosure, though it does not specify pagination behavior or the exact shape of the inner data field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections, making it scannable, and includes an example. However, it wastes space by repeating 'Get Timeline' and duplicating read-only warnings in both 'Risk' and 'Safety warnings.' Overall, it is longer than necessary but well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite weak purpose and partial parameter semantics, the description covers many operational aspects: auth requirements, environment resolution, failure modes, response wrapper, prerequisite tools, and an example. For a complex 14-parameter tool with no annotations, this is a fairly thorough picture, but missing parameter semantics and lack of sibling differentiation leave clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 14 parameters with 0% description coverage, so the description must compensate. It provides a 'Parameter formats and constraints' list for only 8 parameters, and several types are listed as 'unknown' (e.g., 'id (path, unknown, required)') without explaining meaning. It does describe scopeTenantId/scopeUserId/scopeAccountId and credentialKey semantics, but omits authorizationKey and preferredAuthType entirely, and does not explain what id refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Timeline.' which is a minimal phrase that does not explain what a timeline is or whose timeline is retrieved. The 'Use when' section repeats 'Get Timeline' exactly, providing no additional clarity. This is essentially tautological and fails to distinguish from related tools like x_api_get_users_posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some exclusion guidance: 'Do not use when: a more specific auth/configuration tool is required before the API call or you are only exploring; prefer x_schema_discovery or x_query_suggestion first.' It also lists recommended prerequisite and follow-up tools. However, it does not state when to use this over sibling data retrieval tools, nor does it explain the specific scenario for a user timeline versus other user data endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects, permissions, failure modes, or return format. It only states that the resolved X auth scope is returned, leaving most behavioral traits opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action verbs, and contains no filler or repetition. The length is appropriate for the stated purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and no explanation of parameter usage or return behavior, the description leaves important context unaddressed, such as what the connectivity validation returns and how the parameters are combined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the three parameters (scopeUserId, scopeTenantId, scopeAccountId) or how they relate to the requested tenant principal. The parameter names provide minimal self-descriptive meaning, but no additional semantics are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Validate' and 'return', naming Postgres, Vault, X auth scope, and tenant principal. It clearly states the tool's function, though it does not explicitly differentiate it from sibling tools like x_connection_info or x_scope_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement implies use for health-checking connectivity and resolving auth scope, but it does not provide explicit when-to-use guidance or mention alternatives such as x_connection_info/x_scope_info.
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?
With no annotations, the description carries the full burden and does a solid job. It explicitly states 'Risk: read-only,' lists required permissions and OAuth scopes, explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId and credentialKey, details common failure conditions (including rate limits and missing credentials), and provides a safety warning about sensitive data. It does not mention the exact HTTP endpoint or any pagination behavior beyond the pagination_token parameter, but the disclosed behaviors are substantial and clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections (Use when, Do not use when, Risk, Required permissions, Environment-selection behavior, Parameter formats, Expected response shape, Common failure conditions, Recommended tools, Safety warnings, Example). It front-loads the purpose and maintains a logical flow. Minor redundancy exists (repeating 'Get Reposts') and some boilerplate, but overall it is concise and each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters, no output schema, and no annotations, so the description needs to be thorough. It covers auth, environment selection, failure modes, and a generic response shape. However, it does not clarify the actual data semantics of 'Reposts' (what fields are returned, whether it lists repost objects or users, etc.) and the response shape is a generic wrapper with no endpoint-specific detail. The example helps but does not fully compensate for the missing semantic completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain three parameters (id, max_results, pagination_token) with type and path/query context, and the environment-selection section clarifies scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, authorizationKey and preferredAuthType are left unexplained, and max_results semantics (e.g., default, max) are not described. The compensation is partial but meaningful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with "Get Reposts," which is essentially a tautology of the tool name x_api_get_posts_reposts. It does not specify what kind of reposts (e.g., reposts of a specific post, reposts by a user), and it does not distinguish it from sibling tools like x_api_get_posts_reposted_by or x_api_get_users_reposts_of_me. The only differentiating clue is the example using 'id', but the description itself lacks the necessary specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause indicating that exploration or auth configuration should be handled by x_schema_discovery, x_query_suggestion, or auth tools first, and includes recommended prerequisite tools. However, the 'Use when' is a tautology ('Get Reposts') and there is no explicit guidance on when to choose this over the many sibling repost-related tools. The guidance is generic boilerplate rather than tool-specific 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?
With no annotations, the description takes on the full burden and does well: it explicitly states 'Risk: read-only,' lists required OAuth scopes, describes environment-selection behavior, common failure conditions, and safety warnings about sensitive data. This goes well beyond basic disclosure, though it could still be clearer about pagination behavior and the exact content of the response payload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized into labeled sections (risk, permissions, environment behavior, parameters, response, failures, tools, safety, example). There is mild redundancy, such as 'Use when: Get followers' repeating the first sentence, but the structure makes scanning easy and each section adds meaningful content. It earns a 4 despite minor repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and 0% schema description coverage, the description provides a solid amount of context: expected response envelope, failure modes, auth prerequisites, and safety warnings. However, it does not describe what the follower data actually contains, specific pagination behavior, or complete parameter semantics for all 9 parameters. This leaves notable gaps for a 9-parameter API tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially does by explaining the id, max_results, and pagination_token parameter formats, and by describing the scopeTenantId/scopeUserId/scopeAccountId and credentialKey behavior. However, parameters like authorizationKey and preferredAuthType are not explained, and id is not identified as the user ID, leaving several parameters under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get followers,' which is a clear action and resource, but it does not specify that this retrieves followers of a specific user. Given sibling tools like x_api_get_lists_followers and x_api_get_users_following, the description lacks enough detail to differentiate the exact scope. It is not a tautology, but it is too minimal for a tool with many similar siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when: Get followers' line is circular and offers no actionable guidance. 'Do not use when' only mentions generic exploration/auth scenarios and suggests x_schema_discovery or x_query_suggestion, but does not discuss when to prefer this tool over alternative follower/following tools. No concrete exclusions are provided beyond broad exploratory cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does exceptionally well: it explicitly states read-only risk, required OAuth scopes and token types, environment-selection behavior (scopeTenantId plus scopeUserId/scopeAccountId), expected response wrapper shape, common failure conditions, and a safety warning about sensitive data. This goes far beyond a minimal description and gives the agent a clear operational picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, etc.), but it is verbose and contains redundancy: 'Use when: Get following' repeats the tool's vague purpose, and the 'Parameter formats and constraints' section partly duplicates schema type information. There is room to tighten without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides much operational context (auth, environment, failures, safety) but fails to explain the most important domain outcome: what data the response actually contains. The expected response shape is only a generic wrapper and does not state that it returns a list of user objects or how following direction is interpreted. Given no output schema, this is a significant gap. The tool's core semantic is left ambiguous, making the description incomplete for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds path/query context for id, max_results, and pagination_token, and explains the role of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey. However, it does not explain what max_results logically controls or what pagination_token does, and it omits authorizationKey and preferredAuthType entirely. The added context is helpful but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get following,' which is a near-restatement of the tool name and does not specify whether it returns the accounts a user follows or the followers of a user. It lacks a clear statement of the resource and action, unlike siblings like x_api_get_users_followers which are more explicit. The 'Use when: Get following' adds no clarity and is essentially tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Do not use when' clause provides guidance to prefer x_schema_discovery or x_query_suggestion for exploration and notes when auth/configuration tools are needed. It also lists recommended prerequisite/follow-up tools. However, it does not differentiate when to use this tool versus sibling tools like x_api_get_users_followers, and the 'Use when' clause is just a repeat of the vague purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavioral traits: it declares the operation as 'mutating, high-risk,' specifies required OAuth scopes and token types, explains the tenant/auth-resolution behavior (scopeTenantId plus exactly one of scopeUserId/scopeAccountId, credentialKey for non-default profiles), describes the expected response shape, lists common failure conditions, and includes explicit safety warnings. This far exceeds the burden placed by the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections (Use when, Do not use when, Risk, Required permissions, etc.) that are easy to scan. It front-loads the tautological 'Pin List,' which is redundant and wastes a line, but overall the structure is efficient and every other section conveys distinct operational information. It is longer than necessary but not bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description covers a great deal: response shape, failure conditions, prerequisites, environment selection, and an example invocation. The main gap is the lack of a clear definition of the underlying operation (what does 'pin' do?), which is crucial for contextual completeness. Nevertheless, the operational context is largely sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does so by explaining that 'id' is a required path parameter, 'body' is the payload, and it clarifies the mutual exclusivity of scopeUserId/scopeAccountId and the role of credentialKey. This adds meaningful semantics beyond the raw JSON schema. However, it does not clarify authorizationKey or preferredAuthType, and the 'body' format is left open.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Pin List.' which is a direct restatement of the tool name and provides no additional meaning. There is no explanation of what pinning a list entails, what resource is affected, or how it differs from sibling tools like x_api_unpin_list or x_api_get_users_pinned_lists. The 'Use when: Pin List' line is also a tautology, offering zero new information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause that correctly steers away from exploration, suggesting x_schema_discovery or x_query_suggestion. However, it lacks any real 'when to use' context beyond the tautological 'Pin List.' It does not mention specific alternative tools for the same operation, such as unpinning or retrieving pinned lists, leaving the agent without guidance on choosing among related APIs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Delete' without detailing irreversibility, required permissions, the effect of scope parameters, or what happens to dependent data. This feels insufficient for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action verb and resource. It contains no fluff and is appropriately sized for its minimal content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema or annotations, the one-sentence description is insufficient to fully understand the tool's behavior and parameter semantics. It lacks any details about how scoping works, whether authorization is required, or what the response will be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 5 parameters with no descriptions (coverage 0%). The description mentions 'tenant/principal' but does not explain parameters like key, scopeUserId, scopeTenantId, scopeAccountId, or authorizationKey. It adds minimal value beyond the schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and names the resource 'tenant/principal Postgres configuration value', clearly distinguishing it from sibling tools like x_config_get, x_config_set, and x_config_list. This is a clear and unambiguous statement of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, exclusions, or scenarios. It simply states what the tool does without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It explicitly labels the operation as mutating and high-risk, lists required OAuth scopes and token types, and includes a safety warning. It also explains environment-selection behavior for auth resolution, adding substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into sections, but it contains redundancy (e.g., 'Use when: Unpin List' restates the purpose) and generic boilerplate (common failure conditions, recommended tools) that could be trimmed. It is informative but not elegantly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the parameter gap, the description covers auth requirements, environment selection, expected response shape, common failures, related tools, and an example. This is a comprehensive profile for a mutating API tool, though the unclear id/list_id semantics prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. While it clarifies scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, the core parameters 'id' and 'list_id' are only repeated as required path parameters with no meaning explained. This is a significant gap for an unpin operation where the roles of these IDs are critical.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Unpin List' as the core purpose, which is a specific verb+resource pairing. It clearly indicates the tool's function but does not differentiate it from sibling tools like x_pin_list or x_unfollow_list, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely repeats 'Unpin List,' providing no contextual guidance. The 'Do not use when' clause is generic advice applying to all API tools, not specific exclusions or alternatives for this unpin action. No mention of when to prefer this over related list operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the transparency burden. It explicitly declares the read-only risk, bearer token prerequisite, environment-selection behavior via scopeTenantId plus exactly one of scopeUserId/scopeAccountId, and the role of credentialKey. It also lists common failure conditions, expected response shape, and a safety warning about sensitive data—extremely thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with clear section labels and includes an example, which aids scanning. But it has redundancy: 'Use when: Get Compliance Jobs' duplicates the opening sentence, and 'Risk: read-only' is repeated in 'Safety warnings. The length could be reduced without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description covers prerequisites, response shape, failure conditions, environment behavior, and a concrete example. It does not explicitly differentiate from the by-id sibling tool, and some parameter semantics are incomplete, but overall it provides a robust operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains type and status parameter formats, and the environment-selection role of scopeTenantId/scopeUserId/scopeAccountId/credentialKey. However, it does not explain authorizationKey or preferredAuthType semantics, leaving two of the eight parameters without meaningful description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get Compliance Jobs.' which directly restates the tool name without adding specificity. It does not clarify whether this lists all jobs or retrieves a single job, nor does it distinguish from the sibling tool x_api_get_compliance_jobs_by_id. The 'Use when' section repeats the same tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Do not use when' section offers useful direction, telling the agent to prefer x_schema_discovery or x_query_suggestion for exploration. However, the 'Use when' is generic ('Get Compliance Jobs') and provides no explicit comparison to x_api_get_compliance_jobs_by_id or other compliance-related tools, leaving some ambiguity about the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it discloses read-only risk, auth token/scopes, environment-selection behavior, common failure conditions, and a warning about sensitive response data. It does not describe the actual content/returned fields, but the provided transparency is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The labeled sections make the content scannable, but there is redundancy ('Use when: Get Quoted Posts' restates the title; read-only appears twice) and some boilerplate failure conditions that may not apply. Overall it's organized but not tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema, the description covers auth, environment selection, expected response envelope, and an example, but it never specifies the shape or meaning of the quoted-posts data returned, and several parameters remain unexplained. It's adequate for invocation but incomplete for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists parameter formats/constraints for id, max_results, pagination_token, and exclude, and explains scopeTenantId/scopeUserId/scopeAccountId/credentialKey in prose, but omits semantics for authorizationKey, preferredAuthType, and doesn't explain exclude values or pagination token usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Quoted Posts,' a clear verb+resource pairing that identifies the operation. However, it doesn't differentiate from sibling tools like x_api_get_posts_reposts or x_api_get_posts_reposted_by, so it falls short of full specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the tool name ('Get Quoted Posts') and offers no concrete triggers. 'Do not use when' gives generic exploratory guidance and fails to name alternative API tools; recommended prerequisite/follow-up tools are listed but not as decision criteria.
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?
With no annotations, the description takes on full behavioral disclosure. It states 'Risk: read-only', describes environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, explains credentialKey profile selection, and lists common failure conditions and safety warnings. This goes well beyond the schema and provides the agent with a solid understanding of the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections and an example, which aids readability. However, 'Use when: Get usage' is redundant with the tool name, and the read-only risk is repeated in both the Risk line and Safety warnings. It could be tightened without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers many aspects—prerequisites, environment selection, failure conditions, response shape, and safety—which is substantial for a tool with no output schema. However, it fails to state what 'usage' actually means (e.g., API call counts, quota consumption, billing), leaving the tool's core responsibility ambiguous. Given the complexity and lack of output schema, this gap prevents full contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the auth resolution semantics for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and notes days as integer. However, it omits authorizationKey and preferredAuthType entirely, and does not mention that days can also accept a numeric string per the schema. Thus it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get usage,' which merely restates the tool name without specifying what 'usage' refers to (e.g., API usage metrics). The subsequent details like 'X API auth failures' and response shape imply it retrieves API usage, but the primary purpose statement is tautological and does not distinguish this from the many sibling x_api_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when: Get usage' provides no concrete scenario. However, it does offer explicit 'Do not use when' guidance (exploration → prefer x_schema_discovery or x_query_suggestion) and lists recommended prerequisite/follow-up tools (x_connection_info, x_auth_get_scope_credentials, x_api_request). This gives some decision support, but the actual use case remains vague.
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?
With no annotations, the description carries the full burden and does so thoroughly. It clearly states the mutating/high-risk nature, required OAuth scopes, environment-selection behavior, common failure conditions, response shape, and safety warnings. This goes well beyond a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with labeled sections, which aids scanning, but it contains redundancy: 'Use when: Unrepost Post' repeats the purpose, and 'Risk: mutating, high-risk' overlaps with the later safety warning. It is longer than necessary but not excessively bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, mutating API tool with no output schema, the description provides an expected response shape, required permissions, environment-selection behavior, failure conditions, and an example. It is missing detailed semantics for source_tweet_id and some auth parameters, but overall it is sufficiently complete for an agent to invoke the tool with caution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does identify id and source_tweet_id as required path parameters and explains scopeTenantId/scopeUserId/scopeAccountId/credentialKey usage, but it leaves the actual meaning of source_tweet_id and authorizationKey underspecified. The 'unknown' format field provides little value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Unrepost Post,' which directly restates the tool name and provides no additional scope or semantic detail. It does not explain what unreposting a post entails or how it differs from related actions beyond the obvious sibling x_api_repost_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Do not use when' guidance and recommends alternative discovery tools (x_schema_discovery, x_query_suggestion) for exploration scenarios. However, the 'Use when' section is tautological ('Unrepost Post') and it never compares this tool to other mutating post actions like x_api_delete_posts or x_api_unlike_post.
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?
No annotations are provided, so the description carries the burden. It says the tool recommends a 'safe' sequence and explains prerequisites, implying no direct mutations, but it does not explicitly state that it only returns recommendations and never executes API calls. Some useful context is provided, but key behavioral boundaries are left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core purpose and key output details without redundancy. Every word contributes to understanding the tool's role.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 undocumented parameters, no output schema, and a complex set of sibling tools, the description leaves major gaps: it does not explain the expected input format, the shape of the returned sequence, or how auth/scope/mutation details are presented. The tool cannot be reliably invoked based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 5 parameters, and the description gives no hints about how to fill path, limit, intent, method, or includeToolSchemas. The agent cannot infer what these parameters mean or which are relevant to a workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Recommend') and resource ('safe X MCP tool sequence') for a workflow, and additionally specifies what it explains (auth, scope, mutation prerequisites). This distinguishes it from the many sibling x_api_* tools that perform direct operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a workflow' implies usage during workflow planning, but there is no explicit statement about when to use this tool instead of siblings like x_schema_discovery or x_health_check, nor any exclusions. Context is present but alternatives are not mentioned.
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?
With no annotations provided, the description carries the full transparency burden and does so thoroughly. It discloses mutation risk ('Risk: mutating, high-risk'), required OAuth scopes, environment-selection behavior for auth resolution, common failure conditions, and explicit safety warnings. This goes well beyond the schema and provides genuinely useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Environment-selection behavior, Common failure conditions, Safety warnings, Example) that make it easy to scan. It is long but justified by the tool's complexity; the main waste is the redundant 'Use when: Append Chat Media Upload' line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, 0% schema coverage, mutating high-risk) and absence of an output schema, the description covers expected response shape, failure conditions, auth prerequisites, safety warnings, and an example. It is incomplete only in failing to clarify the core operation and in omitting semantics for multipartForm and preferredAuthType.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for id and body ('id (path, string, required); body is used for the documented request payload') and explains scopeTenantId/scopeUserId/scopeAccountId/credentialKey via the environment-selection behavior section. However, it leaves multipartForm (likely the critical media payload for an append operation) and preferredAuthType unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Append Chat Media Upload,' which merely restates the tool name (x_api_chat_media_upload_append) rather than explaining what appending entails or how it fits into a media upload workflow. The 'Use when' line repeats the same tautology, and it does not distinguish this tool from its workflow siblings like x_api_chat_media_upload_initialize and x_api_chat_media_upload_finalize.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit exclusions ('Do not use when: a more specific auth/configuration tool is required... prefer x_schema_discovery or x_query_suggestion first') and lists recommended prerequisite/follow-up tools. However, the 'Use when' clause is tautological, and there is no guidance on when to choose this tool over the closely related chat media upload initialize/finalize siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does exceptionally well. It states 'Risk: mutating, high-risk,' gives required OAuth scopes and token types, explains environment-selection behavior, lists common failure conditions, and includes safety warnings about mutating X state. This is far beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Risk, Required permissions, Environment-selection behavior, Parameter formats, Expected response, Common failures, Recommended tools, Safety warnings, Example) which makes it scannable and front-loaded. It is longer than average but every section adds value, except the redundant opening tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, and zero annotation coverage, the description is remarkably complete. It provides expected response shape, common failure conditions, prerequisites, environment selection behavior, and an example. Still, the vague operation description and missing details for authorizationKey and preferredAuthType keep it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies id as a required path parameter, body as the payload, and explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution. However, it does not explain authorizationKey or preferredAuthType, and the body payload shape is left as 'documented request payload' without further detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Follow List.' which is a tautology that simply restates the tool name, and 'Use when: Follow List.' repeats the same. It does not specify a clear verb+resource or explain what the tool actually does, nor does it distinguish it from sibling tools like x_api_unfollow_list or x_api_get_users_followed_lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' section with explicit exclusions (e.g., exploring, needing auth/config tools) and names x_schema_discovery and x_query_suggestion as alternatives. However, the 'Use when' section is tautological ('Follow List.'), offering no real guidance on when this tool is preferred over similar list-related mutation 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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It includes read-only risk, required OAuth permissions, environment-selection behavior for scope/credential parameters, expected response shape, common failure conditions, and safety warnings, which is exceptionally thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into labeled sections and front-loads the core purpose. However, 'Use when: Get Media analytics' is a tautology that wastes a line, and the parameter list partly repeats the schema. Overall, most sections earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter API tool with no output schema and no annotations, the description provides expected response shape, failure conditions, and prerequisites, which is helpful. But the example omits all required parameters, and optional auth parameters are underexplained, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists the four required parameters with locations and requiredness, and explains some scope/credential parameters, but it does not define the semantic meaning of media_keys or granularity, and omits authorizationKey and preferredAuthType entirely. With 0% schema description coverage, this leaves significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Media analytics', using a specific verb and resource. However, it does not explicitly distinguish this tool from sibling analytics tools like x_api_get_posts_analytics or x_api_get_insights_historical.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' clause simply restates 'Get Media analytics' and provides no situational guidance. The 'Do not use when' section offers only generic exploration advice and does not name alternatives for similar analytics functions, leaving the agent without clear selection criteria.
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?
No annotations are provided, so the description carries the full transparency burden. It discloses read-only risk, bearer token requirement, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, common failure conditions, and safety warnings about sensitive data. This is thorough and goes beyond simple 'safe read' statements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Environment-selection behavior, etc.), making it scannable. However, the 'Use when' section is redundant with the first sentence, and the parameter list repeats schema information. Still, it's not overly verbose and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters and no output schema, the description covers many practical aspects: purpose, auth, failure conditions, response shape, and an example. However, it does not explain the semantic meaning of the search parameters, the definition of 'recent', pagination behavior, or the contents of the response data beyond the envelope. This leaves gaps for an agent needing to construct valid calls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameter names and types, but mostly duplicates the schema (which already has types). It adds 'query' location and 'required' for query, but doesn't explain the meaning of parameters like query, start_time, end_time, granularity, or pagination tokens. The example omits the required 'query' parameter, using only auth scoping parameters, which could mislead an agent about required arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get count of recent Posts', which is a specific verb and resource. It clearly states the tool's function. However, it doesn't explicitly distinguish from the sibling tool x_api_get_posts_counts_all beyond the 'recent' in the name and description; the description could mention the distinction between counting recent vs all posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section simply restates the purpose ('Get count of recent Posts'), providing no new guidance. The 'Do not use when' advice is generic (prefer schema discovery when exploring) and doesn't differentiate from similar counting/search tools. It lacks an explicit comparison to x_api_get_posts_counts_all or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly: it declares the tool read-only, lists required bearer/OAuth tokens and scopes, explains environment-selection behavior, provides expected response shape, common failure conditions, and safety warnings about sensitive data. This goes well beyond a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections (Use when, Risk, Permissions, Parameter formats, Expected response, Common failures, Recommended tools, Safety, Example). The main redundancy is the opening 'Get Reposted by' and its repetition in 'Use when', but the overall organization makes the density acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no output schema and no annotations, the description provides a surprising amount of context: expected response envelope, failure modes, auth requirements, environment-selection behavior, and a concrete example. It is not fully complete because the core purpose and several parameter meanings are vague, but it covers most operational concerns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), so the description must compensate. It does explain id, max_results, and pagination_token formats, and the prose covers scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it never explains the meaning of id (e.g., 'the post ID'), what max_results controls, how pagination_token works, or what authorizationKey and preferredAuthType do, leaving meaningful gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Reposted by', which is essentially a restatement of the tool name and lacks a clear object—it does not explicitly say 'retrieve users who reposted a specified post.' The 'Use when' section repeats the same phrase, adding no specificity and failing to distinguish this from sibling tools like x_api_get_posts_reposts or x_api_get_users_reposts_of_me.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is an explicit 'Do not use when' clause that steers away from exploration and auth/configuration scenarios, and it recommends x_schema_discovery or x_query_suggestion for those cases. However, the 'Use when' is tautological ('Get Reposted by') and provides no concrete conditions for when to invoke this tool over specific 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?
With no annotations provided, the description carries the full transparency burden and does so richly. It discloses read-only nature, bearer token prerequisite, environment-selection behavior for scoped credentials, expected response shape, common failure conditions (including Vault credentials, rate limits, auth failures), and a safety warning about sensitive data in responses. This goes well beyond the structured schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, front-loads the core action, and includes an example. Some redundancy exists (e.g., 'Risk: read-only' and 'Safety warnings' both state read-only), and the 'Use when' line is filler. Overall, the length is justified for a 10-parameter tool without annotations, but slight trimming would improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers many operational aspects: auth prerequisites, environment selection, expected response shape, failure conditions, and safety. However, it lacks clarity on what 'partition' means or valid values, does not explain the purpose of start_time/end_time/backfill_minutes, and provides no details about streaming behavior (e.g., long-lived connection or pagination). These gaps are significant for a 10-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description must compensate. It lists formats/locations for backfill_minutes, partition, start_time, and end_time, and explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution. However, it does not explain the semantic meaning of the time/partition parameters, and entirely omits authorizationKey and preferredAuthType. This leaves significant ambiguity for 4+ parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Stream English Posts', using a specific verb and resource that distinguishes it from language-specific sibling tools like _ja, _ko, and _pt. However, it does not explicitly differentiate from the generic x_api_stream_posts_firehose, leaving slight ambiguity about whether the base version is language-neutral or a superset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' clause is tautological ('Stream English Posts'), providing no decision criteria. The 'Do not use when' clause only mentions exploration and auth/configuration scenarios, directing to x_schema_discovery or x_query_suggestion, but fails to compare against other streaming tools such as x_api_stream_posts_firehose, x_api_stream_posts_sample10, or x_api_stream_posts_sample. Thus, no guidance is given for choosing among streaming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It says 'Resolve' which implies a read/lookup operation, but it does not disclose whether the operation is read-only, what it returns, whether it can fail, or any authentication/rate-limit considerations. The mention of Vault/Postgres adds usage context but not behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence. Every word contributes to the meaning, and it avoids redundancy. It is appropriately concise for the tool's simple lookup nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should explain what the resolved details look like, but it does not. It also lacks information about error cases, return format, or how the details are used. For an agent to confidently invoke the tool and interpret results, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description helps by indicating the scoping patterns: 'tenant/user or tenant/account'. This clarifies that tenantId is combined with either userId or accountId. However, it does not fully specify each parameter's role or whether tenantId alone is valid, leaving some ambiguity that the schema does not resolve.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Resolve tenant/user or tenant/account scoping details used by Vault secret paths and Postgres configuration rows.' It uses a specific verb ('Resolve') and a specific resource ('scoping details'), and the mention of Vault/Postgres differentiates it from sibling tools like x_connection_info or x_config_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to obtain scoping details for Vault paths or Postgres config, but it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria. The purpose is clear, but usage guidance is only implicit rather than direct.
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?
With no annotations, the description carries the full burden. It explicitly discloses 'Risk: mutating, high-risk' and includes safety warnings ('This mutates X state'), required OAuth scopes, and common failure conditions. This goes beyond the bare name and provides useful operational context, though it does not discuss reversibility or the exact public-facing effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Required permissions, etc.) and is front-loaded with the core purpose. It is comprehensive but has minor redundancy, such as the tautological 'Use when: Publish Article.' Overall, it is organized and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description supplies an expected response shape, common failure conditions, required permissions, and safety warnings. This provides a solid operational context. It does not elaborate on every parameter or the full publishing workflow, but for a tool with 7 parameters and no output schema, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the role of scopeTenantId plus exactly one of scopeUserId/scopeAccountId for auth resolution, and that credentialKey selects a non-default credential profile. It also identifies article_id as a required path string. However, it does not clarify authorizationKey or preferredAuthType, leaving some parameters under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Publish Article,' which is a clear verb+resource pair and distinguishes from the sibling tool x_api_article_create_draft. However, it is very terse and does not explain nuances like publishing an existing draft or making an article live.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' condition is tautological ('Publish Article'), and the 'Do not use when' clause is generic (about exploring or using auth tools), not specific to alternatives like x_api_article_create_draft or other article-related tools. There is no clear guidance on when to choose this tool over a more specific sibling.
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?
With no annotations provided, the description carries full burden. It explicitly states the mutation risk, required OAuth scopes, environment-selection behavior, common failure conditions, and a safety warning to validate scope/payload/authorizationKey. This provides substantial transparency beyond the structured schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labels (Use when, Risk, Required permissions, etc.), making it scannable. The example is useful. Minor redundancy exists with 'Use when: Block DMs.' repeating the purpose, but overall it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no annotations, and no output schema, the description provides a comprehensive set of context: permissions, environment-selection, expected response shape, common failures, and recommended related tools. It lacks explicit definition of the 'id' parameter's meaning, but the overall coverage is strong for a wrapper tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does explain auth-related parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) and marks id as path/required, but it does not clarify the semantic meaning of 'id' or 'authorizationKey'/'preferredAuthType'. This partial compensation earns a middle score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Block DMs.', a clear verb+resource statement that conveys the tool's primary action. It also distinguishes itself from the sibling x_api_unblock_users_dms by using the opposite verb. However, it does not explicitly clarify that 'id' refers to a user ID or what exactly gets blocked (e.g., DMs from a specific user).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section simply restates 'Block DMs.', providing no additional guidance on when to choose this tool over other DM-related siblings like x_api_unblock_users_dms or x_api_create_direct_messages_conversation. The 'Do not use when' provides only general exploration/auth exceptions, not tool-specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description fully compensates by disclosing mutating high-risk behavior, required bearer token, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId/credentialKey, common failure conditions, safety warnings, and expected response shape. This is a thorough behavioral disclosure exceeding typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Environment-selection behavior, etc.), making key information easy to scan. Minor redundancy: 'Use when: Delete subscription' repeats the opening line. Overall each section earns its place, and the format is efficient for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers auth, failure, safety, response shape, and includes an example. However, the example omits the required user_id parameter, which is a critical gap for correct invocation. It also doesn't explicitly mention that this deletes an 'account activity' subscription. With 8 parameters and no output schema, the example flaw significantly undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, so the description must explain all 8 parameters. It adds meaningful semantics for environment-selection parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) and identifies required path params. However, authorizationKey and preferredAuthType are left unexplained, and parameter formats are marked 'unknown', providing only partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete subscription.' which is a clear verb+resource, but uses the generic term 'subscription' rather than 'account activity subscription' from the tool name. It fails to differentiate from sibling tools like x_api_delete_activity_subscription or x_api_delete_activity_subscriptions_by_ids, making the purpose somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides 'Use when' and 'Do not use when' sections with explicit advice to prefer x_schema_discovery or x_query_suggestion for exploration and to use auth/configuration tools first when needed. However, it does not compare against alternative subscription deletion tools, so an agent cannot decide when this tool is the best choice among similar siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and does so thoroughly. It discloses read-only status, safety warnings about sensitive data, failure conditions including rate limits and auth failures, and explains environment-selection behavior. This exceeds typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it contains redundancy such as 'Get OpenAPI Spec..' appearing twice and 'Risk: read-only' repeated in the safety warning. Some sections are useful but the wording could be tightened without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite weak purpose clarity, the description provides a response shape, an example invocation, failure conditions, environment-selection behavior, and recommended companion tools. This gives an agent enough context to select and invoke the tool correctly, though the missing parameter details slightly reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description partially compensates by explaining scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in the environment-selection section. However, it omits authorizationKey and preferredAuthType, and the line 'Parameter formats and constraints: no endpoint-specific parameters' is confusing, leaving some parameters under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get OpenAPI Spec..' which essentially restates the tool name without elaborating on what the OpenAPI spec contains or how it relates to the X API. It lacks a specific verb+resource+scope that distinguishes it from siblings; the 'Do not use when' section points to alternatives but the core purpose remains underspecified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is an explicit 'Do not use when' clause naming x_schema_discovery and x_query_suggestion as better fits for exploration, plus a 'Recommended prerequisite and follow-up tools' list. The 'Use when' section is tautological ('Get OpenAPI Spec..'), but the exclusion and alternatives provide clear usage guidance, so this is above baseline.
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?
No annotations are provided, so the description carries the full burden. It clearly warns that this is a mutating, high-risk operation, lists required OAuth scopes and token types, describes environment-selection behavior, common failure conditions, and safety warnings. This goes well beyond the schema and gives the agent important execution context, though it does not explain reversibility or specific side effects beyond 'mutates X state'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections, making it scannable. However, the opening 'Mute User.' and the 'Use when: Mute User.' line are redundant and waste tokens. Other sections are dense but relevant, so overall it is acceptable but not tightly written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-risk mutation tool with no annotations and no output schema, this description provides useful context: expected response shape, common failures, recommended pre/post tools, and safety warnings. But it leaves critical details ambiguous, such as what the 'id' refers to, what the body should contain, and the exact effect of muting. This prevents it from being fully complete for autonomous invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaning for scopeTenantId, scopeUserId/scopeAccountId, credentialKey, id, and body, explaining auth resolution and required path parameter. However, it does not explain the semantics of authorizationKey or preferredAuthType, and the statement 'id (path, unknown, required)' leaves the meaning of 'id' unclear. Body structure is also not documented, only noted as 'the documented request payload'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Mute User', a clear verb+resource statement indicating the tool's action. It does not explicitly differentiate from sibling tools like x_api_unmute_user or x_api_get_users_muting, but the action is unambiguous. The rest of the description adds context, so it is not merely a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' field is entirely tautological ('Mute User'), providing no meaningful guidance. The 'Do not use when' section correctly discourages using this tool for exploration or when auth/configuration setup is needed, but it does not compare against alternative muting-related API tools. Usage context is implied rather than explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does an exceptional job: it declares read-only risk, required permissions (bearer token), detailed environment-selection behavior (scopeTenantId plus exactly one of scopeUserId/scopeAccountId, credentialKey), expected response wrapper shape, common failure conditions (Vault creds, X API auth, rate limits), and safety warnings about sensitive data. This far exceeds typical tool descriptions and gives the agent concrete behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear labeled sections (Use when, Risk, Parameter formats, Expected response shape, etc.) making it scannable and well-structured. However, the opening 'Use when: Search all Posts' is redundant with the first sentence, and the parameter list is long but not inherently verbose. Overall it is reasonably concise for the complexity, but it could trim redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter tool with no output schema, the description covers a lot: auth prerequisites, environment selection, failure modes, recommended companion tools, and safety. But it lacks any detail about the actual post data returned (only the generic wrapper), and it does not explicitly clarify the difference from 'recent' search or how pagination works beyond listing the tokens. These gaps are notable given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only restates parameter names and types without explaining semantics (what start_time, since_id, or pagination_token actually control). It even misrepresents max_results as solely an integer, while the schema allows strings matching a numeric pattern. The environment parameters get some explanation, but the core query parameters are effectively undocumented, leaving the agent without enough meaning to construct correct arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb and resource ('Search all Posts'), but it is a near-tautology of the tool name and provides no additional detail about what 'all' means (e.g., full-archive vs. current history). It does not distinguish this tool from the closely named sibling x_api_search_posts_recent, relying on the name alone. The 'Use when' section simply repeats the purpose without adding specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some usage exclusions: 'Do not use when... only exploring; prefer x_schema_discovery or x_query_suggestion first' and notes prerequisites like bearer token. However, it never explicitly contrasts with the analogous recent-search tool (x_api_search_posts_recent) or other search tools, leaving the 'when to use this vs. that' decision mostly to the agent's inference. The guidance is present but generic.
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?
With no annotations, the description carries the full burden. It does disclose that deletion affects both Vault and Postgres metadata, which is a useful behavioral detail. However, it omits important traits such as irreversibility, required permissions, and what happens if the profile does not exist. Thus, it provides partial but not comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb 'Delete' and delivers the essential action. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters, no output schema, and no annotations, a one-sentence description is inadequate. It lacks parameter semantics, error behavior, return value expectations, and usage guidance. The description is too sparse to support correct invocation of all parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fails to explain the optional parameters (userId, accountId, authorizationKey) and does not clarify the relationship between profileType and the described resource. The property names are somewhat self-explanatory, but several parameters remain ambiguous without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the specific resource ('stored tenant-scoped app profile or tenant/principal credential profile') along with the target systems ('Vault and Postgres metadata'). This distinguishes it from sibling tools like x_auth_upsert_app_credentials and x_auth_get_scope_credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: deleting auth profiles. However, it does not explicitly state when to use this tool vs alternatives (e.g., x_config_delete) or mention prerequisites like authorizationKey or tenant context. No when-not conditions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses read-only risk, bearer token requirement, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This goes well beyond basic safety hints and gives the agent useful behavioral context for invoking the tool correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into labeled sections and is information-dense, but the 'Use when' line repeats the first sentence and read-only is mentioned twice. Still, it earns its length given the tool complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It provides response shape, failure conditions, prerequisites, an example, and safety notes, which is strong for a complex tool without an output schema. However, it misses parameter semantics and does not clarify the relationship with counts_recent, so some context is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It lists several parameter names and types and explains scopeUserId/scopeTenantId/credentialKey selection, but it does not define the meaning of query, granularity, or the since_id/until_id/next_token/pagination_token fields, leaving significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get count of all Posts,' which is a clear verb+resource statement. However, it does not explicitly differentiate from sibling tool x_api_get_posts_counts_recent or clarify that 'all' refers to full-archive vs recent counts, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line merely restates the purpose and provides no situational guidance. The 'Do not use when' gives generic advice to prefer x_schema_discovery or x_query_suggestion when exploring, but does not specify when to choose this tool over counts_recent or related search 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?
With no annotations, the description carries the full burden for behavioral disclosure. It explicitly states risk is read-only, required permissions (bearer/OAuth scopes), environment-selection behavior for tenant/auth resolution, common failure conditions, and a safety warning about sensitive data. This is comprehensive and goes far beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structured with clear labeled sections including risk, permissions, parameter formats, response shape, failures, and an example. It is front-loaded and every section adds value, though the repeated 'Get List memberships' phrases are somewhat redundant. Overall, the structure aids readability despite density.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 9-parameter tool with no output schema, the description is exceptionally complete. It includes expected response shape, common failure conditions, auth requirements, and a concrete example. It also covers environment-specific behavior and safety warnings, ensuring an agent has enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the 9 parameters. It explains id, max_results, pagination_token, and the scopeTenantId/scopeUserId/scopeAccountId/credentialKey relationship. However, it omits authorizationKey and preferredAuthType entirely, and some descriptions are vague (e.g., id listed as 'unknown' despite schema indicating string). Partial but not complete compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description's core statement, 'Get List memberships,' merely restates the tool name without adding specificity. It does not clarify that this returns memberships for a user, which is important to distinguish from sibling tools like x_api_get_lists_members. The 'Use when' section repeats the same phrase, reinforcing the tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance, including preferring x_schema_discovery or x_query_suggestion for exploration, and lists recommended prerequisite tools. However, the 'Use when' clause is just a restatement and does not clearly define the exact scenario for this tool versus other list-related endpoints. Still, it offers sufficient exclusions and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so excellently. It declares read-only risk, required OAuth scopes, environment-selection behavior for tenant/account resolution, expected response shape, and common failure modes (auth failures, rate limits). It also warns that responses may contain sensitive data, adding valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear section headings (Risk, Required permissions, Parameter formats, Expected response shape, etc.). Redundancies exist ('Get Posts' appears twice, read-only stated twice), but the structured format makes the information scannable and each section adds relevant detail for such a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers auth prerequisites, environment selection, response shape, failure conditions, and an example invocation, which is substantial for a 14-parameter tool with no annotations or output schema. It is not perfect, as it does not explicitly differentiate itself from sibling post-retrieval tools or clarify the semantics of the id parameter, but it provides enough for an agent to proceed in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by listing parameter formats and constraints, specifying path vs query context for id, since_id, etc., and types for some. However, it omits several parameters (authorizationKey, preferredAuthType) and does not explain the semantic meaning of 'id' or the filtering/response implications of parameters like exclude, start_time, and end_time.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Posts,' which states the verb and resource but lacks specificity about whose posts are retrieved or how this differs from other post-fetching tools like x_api_get_posts_by_id or x_api_get_users_timeline. It does not explain that this tool retrieves a user's posts by user ID, making the purpose vague at the operational level despite the name hinting at it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when: Get Posts' is circular and unhelpful, merely restating the purpose. However, the 'Do not use when' section gives explicit guidance to prefer schema discovery or query suggestion for exploration, and it lists recommended prerequisite tools, providing some context but not comparing this tool to similar post-fetching alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It explicitly states mutating/high-risk behavior, required OAuth scopes, environment-selection rules, failure conditions, and safety warnings. This goes far beyond basic disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it is verbose and contains redundancy (e.g., 'Use when: Send Typing Indicator' merely repeats the purpose). The example is helpful, but the overall length is not tightly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema and annotations, the description provides expected response shape, common failure conditions, recommended prerequisite/follow-up tools, and an example. This is comprehensive for a simple tool, though some parameter gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the role of id (path, required), scopeTenantId with exactly one of scopeUserId/scopeAccountId for auth resolution, and credentialKey for non-default profiles. However, it omits explanation for authorizationKey and preferredAuthType, leaving two parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Send Typing Indicator', a specific verb and resource that clearly identifies the tool's function. It is distinguishable from siblings like x_api_send_chat_message, though it doesn't explicitly state the target (e.g., 'to a chat conversation').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line merely restates the tool name ('Send Typing Indicator') with no additional context. The 'Do not use when' provides only generic guidance about preferring discovery tools, not specific alternatives for this operation. No concrete scenario is given for when this tool should be chosen over sibling chat 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?
With no annotations provided, the description fully discloses the mutating and high-risk nature: 'Risk: mutating, high-risk' and 'Safety warnings: This mutates X state.' It also details required permissions, expected response shape, common failure conditions, and environment-selection behavior. This goes beyond minimal disclosure and gives the agent a clear picture of side effects and safety requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with labeled sections, which aids scanning, but it contains redundancy: 'Unlike Post' appears in both the opening and 'Use when', and 'mutating, high-risk' is stated in both the Risk line and the Safety warning. The length is moderate but could be tightened without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the parameter-semantics weaknesses, the description covers many contextual aspects: expected response shape, required permissions, common failure conditions, recommended prerequisite tools, environment selection, and a (flawed) example. This is fairly complete for a complex tool, though the missing explanation of core id/tweet_id and the incomplete example prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does explain environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, but for id and tweet_id it only says '(path, unknown, required)' which is vague and misleading ('unknown'). The example omits the required tweet_id parameter, further confusing parameter usage. authorizationKey and preferredAuthType are not explained at all. This is insufficient for an 8-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Unlike Post.' which is a specific verb+resource statement that clearly identifies the tool's action. It distinguishes from related sibling tools like x_api_like_post by using the opposite verb, though it could be more explicit about the scope (e.g., removing the authenticated user's like from a post). The phrase 'Use when: Unlike Post' is tautological, but the primary purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage guidance: 'Do not use when' covers exploration and suggests preferring x_schema_discovery or x_query_suggestion, and recommends auth/configuration tools when needed. However, the 'Use when' is just a restatement of the purpose and there is no explicit comparison to alternative action tools like x_api_like_post. This is adequate but not strong.
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?
With no annotations, the description carries the full burden and does so thoroughly: it labels the risk as 'mutating, high-risk,' states that it mutates X state, lists required auth tokens, explains environment-selection behavior, and enumerates common failure conditions. This is exemplary transparency for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (risk, permissions, environment, params, response, failures, prerequisites, safety, example), making dense information scannable. The redundant 'Use when: Validate webhook' adds little value and slightly undercuts conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and an output schema, the description is remarkably complete: it covers required permissions, environment selection, expected response shape, common failures, safety warnings, and provides a concrete example. This is sufficient for an agent to make a reasonably safe and informed invocation decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It meaningfully explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey auth-scoping behavior, and tags webhook_id as a required path parameter. However, it never defines authorizationKey or preferredAuthType, leaving two of the seven parameters semantically underexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The core description is a near-verbatim restatement of the tool name ('Validate webhook') with no elaboration on what validation actually does—whether it sends a test event, checks endpoint reachability, or returns configuration status. The expected response shape hints at an HTTP-style result, but the purpose statement itself is tautological and does not clearly distinguish the operation beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance and names alternatives (x_schema_discovery, x_query_suggestion), plus a 'Recommended prerequisite and follow-up tools' section. However, the 'Use when' clause is circular ('Validate webhook') rather than describing a concrete scenario, which prevents a perfect score.
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?
With no annotations, the description carries full burden and excels: it explicitly states mutating risk, required OAuth scopes, environment-selection behavior, common failure conditions, and safety warnings. This goes well beyond baseline and fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loads the core action. The opening 'Use when: Create List' is redundant and wastes a sentence, but the rest is concise and information-dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is rich on auth, scoping, failure modes, and response envelope. However, it lacks any specification of the actual list payload (e.g., required fields like name), which is essential for an agent to create a list correctly. It defers to 'documented request payload' without providing that documentation, leaving a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the critical tenant/principal selection parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) and clarifies that 'body' holds the request payload. However, it does not explain authorizationKey or preferredAuthType, and the body contents are left unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create List', which is a clear verb+resource but essentially echoes the tool name. It does not distinguish this tool from sibling list tools beyond the obvious create vs. read/update/delete. No detail on what a 'list' is in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' is tautological ('Create List'). However, it provides a useful 'Do not use when' clause and recommends prerequisite tools (x_schema_discovery, x_query_suggestion) for exploration, plus lists related tools. It does not explicitly compare to alternative list mutation tools like x_api_update_lists.
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?
With no annotations provided, the description fully carries the behavioral transparency burden and excels. It discloses mutating/high-risk nature, required OAuth scopes, environment-selection behavior, common failure conditions, and safety warnings, providing rich context beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it contains redundancies such as repeating 'Create Bookmark' and mentioning 'mutating' twice. It is longer than necessary and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description comprehensively covers permissions, failure conditions, expected response shape, and environment-selection behavior. However, the actual request payload (body) is left underspecified, which is a critical gap for an action tool with no output schema or schema property descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to several parameters (id, body, scopeTenantId, scopeUserId, scopeAccountId, credentialKey) but leaves authorizationKey and preferredAuthType unexplained. Since schema coverage is 0%, it only partially compensates, and the body parameter's structure is vaguely referenced as 'documented request payload.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with "Create Bookmark," a clear verb+resource statement that distinguishes this tool from sibling tools like x_api_delete_users_bookmark and x_api_get_users_bookmarks. However, it does not explicitly mention that it operates on a user's bookmarks and closely mirrors the tool name, so it adds limited specificity beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes "Use when: Create Bookmark" which is tautological, and "Do not use when" provides a useful exclusion for exploration and auth/config prerequisites. It does not explicitly contrast with alternative bookmark operations or other x_api_request tools, so guidance is only partial.
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?
With no annotations, the description carries full burden and does well: it discloses mutating/high-risk nature, requires bearer token, explains environment-selection behavior for auth resolution, lists common failure conditions, and includes safety warnings. It lacks specifics on permanence or cascading effects of deletion, but provides solid behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections and front-loaded purpose. It is slightly redundant ('Use when: Delete stream link' repeats the purpose; 'Risk' and 'Safety warnings' overlap) but remains compact given the tool's complexity. The example is useful and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers purpose, risk, permissions, auth scoping, response shape, failure conditions, prerequisites, and example, which is quite complete for a 7-parameter tool with no output schema. Gaps remain in parameter documentation (authorizationKey, preferredAuthType) and some delete-specific behavior, but the description is sufficient for an AI agent to invoke the tool safely in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It does explain webhook_id as a path parameter and clarifies the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution. However, authorizationKey and preferredAuthType are not addressed, and webhook_id's format is vague ('unknown'). The example shows typical arguments, adding some practical meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete stream link' with a specific verb and resource, distinguishing it from sibling tools like x_api_get_webhooks_stream_links and x_api_create_webhooks_stream_links. However, it doesn't elaborate on what a stream link is or the full implications of deletion, relying on the tool name for context. The 'Use when' line is tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' is tautological ('Delete stream link'). The 'Do not use when' provides some guidance for exploration/auth-config scenarios and suggests alternatives like x_schema_discovery and x_query_suggestion, but it doesn't explicitly compare to sibling tools for deleting stream links. Recommended prerequisite/follow-up tools add some context but no specific when-to-use vs. create/get alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses read-only risk, required OAuth scopes, environment-selection behavior, common failure conditions, and a safety warning about sensitive account data. This goes well beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections but is verbose, repeating 'Search News' and 'read-only' multiple times. Some information (parameter types) duplicates the input schema, though the labels aid scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers response shape, failure conditions, prerequisites, and gives an example, which is useful given no output schema. However, it does not explain the actual content of the returned `data` (e.g., a list of news articles) or pagination behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the meaning of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in the environment-selection behavior, and lists query, max_results, and max_age_hours with types. However, it omits authorizationKey and preferredAuthType, and does not clarify query syntax or valid ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search News' and repeats 'Use when: Search News', which is tautological. It does not define what 'News' means in the X API context or differentiate this from sibling tools like x_api_get_news or x_api_search_posts_recent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit 'Do not use when' guidance (prefer x_schema_discovery or x_query_suggestion when exploring) and lists recommended prerequisite tools, but the core 'Use when' is circular and there is no comparison to other search 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?
With no annotations, the description carries the full burden and does well: it declares read-only risk, required OAuth scopes/token types, environment-selection behavior for tenant/account scopes, expected response shape, common failure conditions, and safety warnings about sensitive data. It does not detail pagination behavior, but overall it is thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured into labeled sections. The 'Use when: Search Users' line is redundant and wastes space, yet the rest of the content is information-dense and organized, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 params, no annotations, no output schema), the description provides essential context: expected response shape, common failures, required permissions, environment selection, and a usage example. It lacks explicit pagination instructions but covers most operational needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does add meaning for scopeTenantId/scopeUserId/scopeAccountId and credentialKey by explaining their role in auth resolution. However, core parameters like query, max_results, and next_token are merely restated with types/constraints from the schema, with no semantic explanation of their meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search Users', which is a specific verb+resource pair. It lacks explicit differentiation from sibling tools like x_api_get_users_by_username, but the verb 'search' sufficiently distinguishes it from direct user lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Do not use when' clause with alternatives for exploration (x_schema_discovery, x_query_suggestion) and recommended prerequisite/follow-up tools. However, the 'Use when' condition is an unhelpful tautology ('Search Users'), providing no real guidance on when this tool should be chosen over similar search or user-related 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?
With no annotations, the description carries full burden and covers a lot: read-only risk, bearer token requirement, environment-selection behavior via scopeTenantId/scopeUserId/scopeAccountId, common failure conditions, expected response shape, and a safety warning about sensitive data. It does not clarify streaming-specific behaviors like connection lifetime or rate-limit handling in detail, but the given information is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections, making it easy to scan. It front-loads the core purpose and groups details logically. Minor redundancy exists: 'Risk: read-only' is repeated in 'Safety warnings,' and the 'Use when' section merely repeats the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema, no annotations), the description provides a solid amount of context: expected response shape, common failure conditions, prerequisites, and an example. However, not all parameters are covered, and the example is incomplete (missing partition), leaving some gaps for an agent to fully invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explicitly lists formats for backfill_minutes, partition, start_time, and end_time, and explains the role of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey. However, it omits authorizationKey and preferredAuthType, and the provided example lacks the required 'partition' parameter, which could mislead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream Korean Posts,' which is a specific verb+resource pair. It clearly identifies the tool's function, but it does not explicitly differentiate from sibling firehose tools like x_api_stream_posts_firehose_en or _ja, relying on the 'ko' in the tool name to imply the language focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line is a tautology ('Stream Korean Posts'), adding no guidance. However, the 'Do not use when' section gives useful exclusions (avoid if auth/config needed or when exploring; prefer x_schema_discovery or x_query_suggestion), and a recommended prerequisite list is provided. Still, it lacks explicit comparison to sibling language-specific firehose 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?
With no annotations provided, the description carries the full burden and does well: it declares read-only risk, explains auth resolution via scopeTenantId/scopeUserId/scopeAccountId and credentialKey, lists common failures, and gives an expected response shape. This goes well beyond a minimal description, though it omits streaming-specific behavior like pagination or connection persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it is somewhat verbose and repetitive (e.g., 'Risk: read-only' is repeated in the safety warning, and 'Use when' repeats the purpose). It is front-loaded with the key action, but not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex stream tool with 10 parameters and no annotations, the description covers purpose, auth prerequisites, environment selection, parameter formats, failure conditions, safety, and an example. It leaves a few gaps (e.g., semantics of partition, stream behavior), but overall it is comprehensive enough for an agent to select and invoke the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions, so the description compensates by listing formats for backfill_minutes, partition, start_time, end_time, and explaining the environment-selection behavior for scoped parameters. It covers most parameters but omits authorizationKey and preferredAuthType, and does not explain the semantic meaning of 'partition' despite marking it required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Stream Portuguese Posts'), which distinguishes it from sibling language-specific streams. However, it does not explicitly mention 'firehose' or clarify whether 'Portuguese' refers to language or region, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line is tautological, but the 'Do not use when' section provides meaningful exclusions and recommends x_schema_discovery or x_query_suggestion for exploration. It also lists prerequisite and follow-up tools, giving some guidance, though it does not explicitly differentiate among language-specific stream 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?
With no annotations, the description carries the full burden and does so thoroughly. It explicitly states 'Risk: mutating, high-risk' and includes a 'Safety warnings' section saying 'This mutates X state.' It also discloses required OAuth scopes, environment-selection behavior, expected response shape, and common failure conditions (auth failures, rate limits, missing credentials), which provides substantial behavioral context beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Environment-selection behavior, etc.), making it scannable. It is somewhat verbose but most sections earn their place. There is minor redundancy: 'Unfollow List.' appears as the first line and again under 'Use when: Unfollow List.' which is a tautology, but overall it remains appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating 8-parameter tool with no annotations and no output schema, the description covers a lot: purpose, exclusions, risk, permissions, environment behavior, response shape, failure modes, and a safety warning. However, it falls short on explaining the critical id/list_id parameters and provides an incomplete example that omits the required list_id. These gaps prevent it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It lists 'id (path, unknown, required); list_id (path, unknown, required)' but adds no meaning for these fields—'unknown' is unhelpful and the description never explains that id is the user ID and list_id is the list ID. It does explain scope-related parameters in the environment-selection section, but the core id/list_id semantics remain ambiguous. The example omits the required list_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Unfollow List.' which identifies the action (unfollow) and resource (list) with a specific verb. It is clear enough, though terse, and the name itself is self-explanatory against sibling tools like x_api_follow_list. However, it doesn't elaborate on what 'unfollow' entails (e.g., removing the authenticated user from the list's followers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when: Unfollow List.' is a tautology that adds no guidance. However, the description provides a 'Do not use when' clause directing agents to x_schema_discovery or x_query_suggestion for exploration and to auth/configuration tools when needed. It also lists recommended prerequisite/follow-up tools, giving some workflow context, but it doesn't explicitly compare against alternative list tools like x_api_follow_list.
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?
With no annotations provided, the description carries the full burden. It discloses that credentials are redacted and that Vault secret existence is checked, which are important behavioral traits. However, it does not mention permissions or potential edge cases like empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and contains no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters and no output schema, the description is too sparse. It omits return format, parameter semantics, and filtering behavior, making it insufficient for correct invocation beyond the required tenantId.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate by explaining parameters. It only hints at 'tenant principal', which may map to tenantId, but leaves userId, accountId, and include flags unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists redacted credential metadata and indicates Vault secret existence, using the specific verb 'List' and defining the scope ('for the selected tenant principal'). This distinguishes it from sibling write tools like x_auth_upsert_* and x_auth_delete_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context about the target (selected tenant principal) but no explicit guidance on when to use this tool versus alternatives. The read-only nature is implied by 'List' but not stated explicitly.
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?
No annotations are provided, so the description carries full burden. It adds some context by labeling the data as 'non-secret' and the operation as 'inspect', implying safety. However, it does not disclose pagination behavior, filter semantics, authentication requirements, or whether all rows are returned when no filters are applied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no filler. Every sentence contributes to understanding the tool's purpose and usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four optional parameters and zero schema descriptions, the description leaves critical invocation details unexplained. While it names what the tool lists, it does not clarify how the scope parameters or prefix affect results, nor does it mention pagination or return structure (no output schema exists). This is insufficient for reliable correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the four parameters (prefix, scopeUserId, scopeTenantId, scopeAccountId). The phrase 'tenant/principal' loosely maps to scopes but provides no specific meaning or interaction details, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List tenant/principal Postgres configuration rows'. It further specifies what the tool inspects: 'persisted non-secret defaults, profile settings, and runtime behavior flags', which distinguishes it from sibling tools like x_config_get, x_config_set, and x_config_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use: 'Use this to inspect persisted non-secret defaults, profile settings, and runtime behavior flags.' It implies a read-only inspection use case and excludes secrets, but does not explicitly name alternatives such as x_config_get 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the persistence nature and non-secret scope but omits details like overwrite behavior, response format, required permissions, or error semantics. The 'non-secret' warning adds useful behavioral context, but overall the disclosure is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and then usage constraints. No redundant information or filler. The description is appropriately concise for its function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no output schema, and no annotations. The description covers the basic purpose and usage boundaries but does not explain the scoping model, how values are stored/retrieved, or the meaning of authorizationKey. For a setter that could be used across tenant/principal/account scopes, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It hints at 'tenant/principal' scope and 'value' but does not explain key naming conventions, the relationship between scopeUserId/scopeTenantId/scopeAccountId, or the authorizationKey parameter. This only partially compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Persist a tenant/principal Postgres configuration value.' It uses a specific verb ('persist'), identifies the resource ('configuration value'), and distinguishes from sibling tools by emphasizing 'non-secret runtime defaults and solution-specific settings' and explicitly excluding tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('non-secret runtime defaults and solution-specific settings') and a clear when-not-to-use ('do not store tokens here'). However, it does not name specific alternative tools (e.g., x_auth_upsert_principal_credentials), so it falls slightly short of a 5.
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?
With no annotations, the description fully bears the burden of disclosing behavior. It clearly states the tool is mutating and high-risk, warns that it mutates X state, lists required OAuth scopes, explains environment-selection behavior for auth resolution, describes expected response shape, and enumerates common failure conditions. This is exemplary transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with labeled sections (e.g., Risk, Required permissions, Expected response, Common failures). Each section provides substantive information without redundancy. It is not maximally concise, but the organized format aids scanning and comprehension, justifying the length given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers a wide range of contextual details: authentication requirements, environment selection, response format, failure conditions, and safety warnings. It omits explicit parameter descriptions for authorizationKey and preferredAuthType, and does not mention what happens if the user is already followed. However, given the 8-parameter schema and no output schema, the description is substantially complete and would guide an agent effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains id is a required path parameter and body is the payload, and it clarifies the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution. However, it does not explain authorizationKey or preferredAuthType, leaving two parameters undocumented. The description adds value but is incomplete for full parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Follow User,' which directly restates the tool name and lacks specification of what following entails (e.g., creating a follow relationship). It is distinguishable from siblings like x_api_unfollow_user by name, but the description itself does not articulate the scope or effect beyond the verb. The additional context about mutating state adds some clarity, but the core purpose statement is essentially a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Use when: Follow User,' which is tautological, but it also provides explicit exclusions: 'Do not use when... prefer x_schema_discovery or x_query_suggestion first.' It names recommended prerequisite tools and clarifies that this is for direct API follow actions, not exploration or configuration. While it does not compare against alternatives like x_api_request, the guidance is sufficient and actionable.
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?
With no annotations, the description fully discloses behavior: it declares 'Risk: read-only,' lists required OAuth scopes and token types, explains environment-selection behavior for tenant principal resolution, gives an expected response shape, enumerates common failure conditions, and includes a safety warning about sensitive account data. This goes well beyond basic hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear labeled sections and is reasonably concise given the complexity. The main redundancy is 'Use when: Get Chat Conversation,' which duplicates the opening sentence. Otherwise, every section adds useful context without excessive fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only GET tool with 7 parameters and no output schema, the description covers prerequisites, environment selection, expected response shape, failure conditions, and safety. It doesn't define what a chat conversation is in this API context, but overall it's quite complete for an agent to invoke the tool successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaningful semantics for id, scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. It explains the auth resolution rule ('scopeTenantId plus exactly one of scopeUserId or scopeAccountId') and the role of credentialKey. However, authorizationKey and preferredAuthType are not explained, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Chat Conversation,' which is a clear verb+resource but essentially restates the tool name. It doesn't explicitly distinguish from the sibling 'x_api_get_chat_conversations' (plural) or describe what a chat conversation is, though the singular form implies a single conversation retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Do not use when' section provides exclusions (auth/configuration tools, exploring) and recommends x_schema_discovery or x_query_suggestion first. It also lists recommended prerequisite/follow-up tools, but the 'Use when' section is tautological ('Get Chat Conversation') and doesn't clarify when to use this over the plural variant or x_api_request.
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?
With no annotations provided, the description carries the full burden and excels. It discloses the read-only risk, required OAuth scopes and token types, environment-selection behavior using scopeTenantId/scopeUserId/scopeAccountId, credentialKey behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This goes well beyond the schema and gives the agent a comprehensive behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear labeled sections. It contains redundant content ('Use when: Get Chat Conversation Events' repeats the title) and the example adds bulk, but every other section carries meaningful information. For a tool with 9 parameters and no annotations, the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers prerequisites, environment selection, parameter constraints, response shape, and failure conditions, making it quite complete for a read-only API wrapper. However, it does not define what counts as an 'event' or explain the meaning of the response data fields beyond the generic envelope, leaving some room for additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the path/query formats for id, max_results, and pagination_token, and provides critical context for environment-selection parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey). However, it omits some parameters like authorizationKey and preferredAuthType, and does not fully explain the interaction between all parameters, so it is not perfect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves chat conversation events with a specific verb and resource. However, it does not explicitly differentiate from sibling tools like x_api_get_chat_conversation, x_api_get_chat_conversations, or x_api_get_direct_messages_events, leaving some ambiguity for an agent choosing among similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the tool's purpose ('Get Chat Conversation Events') without providing actionable context. The 'Do not use when' section offers generic advice about exploring or requiring auth tools, but does not name alternatives specific to this operation, such as x_api_get_chat_conversation for conversation details or x_api_get_direct_messages_events for DM events. This leaves the agent without clear guidance on when to choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states risk (read-only), required permissions and OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This is exemplary in transparency, earning a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into labeled sections and covers many aspects without unnecessary fluff. The only redundancy is the opening 'Get List Posts. Use when: Get List Posts.' which wastes a sentence. The rest is appropriately concise, earning a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description provides response shape, failure modes, prerequisites, environment-selection behavior, and safety considerations. It leaves little ambiguity and is complete enough for an agent to invoke correctly, earning a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining 7 of 9 parameters: id, max_results, pagination_token, scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. It describes their roles and constraints, though authorizationKey and preferredAuthType are not explicitly discussed. This is strong compensation, a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get List Posts,' which is essentially a rephrasing of the tool name 'x_api_get_lists_posts.' It does not explain what list posts are or how this tool differs from sibling tools like x_api_get_posts_by_id or x_api_get_lists_by_id. The purpose is tautological, providing no real differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Do not use when' guidance with alternatives (x_schema_discovery, x_query_suggestion) and lists recommended prerequisite and follow-up tools. However, the 'Use when' clause is just 'Get List Posts,' which is unhelpful. Overall, the exclusions and alternatives earn a 4.
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?
With no annotations, the description carries the full transparency burden and succeeds. It declares read-only risk, required bearer/OAuth tokens and scopes, environment-selection behavior for tenant resolution, expected response shape, common failure conditions, and a safety warning about sensitive account data. This is far more than minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose. However, the 'Use when' line is a redundant restatement of the title, and the example is incomplete (missing required ids), which undermines the structure's utility. It is longer than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and complex auth requirements, the description covers response envelope, failure conditions, permissions, environment selection, and safety warnings. The main gap is that it does not describe the content of the inner 'data' field (the actual post objects) or how multiple IDs should be formatted in practice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds meaningful semantics for ids (query, required) and explains how scopeTenantId/scopeUserId/scopeAccountId/credentialKey affect auth resolution. However, it inaccurately limits ids to 'array' when the schema allows string or array, omits authorizationKey and preferredAuthType semantics, and the example omits the required ids parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Posts by IDs,' which clearly identifies the action and resource, and the plural 'IDs' hints at batch retrieval, distinguishing it from the singular sibling x_api_get_posts_by_id. However, it mostly restates the tool name and does not explicitly describe the batch semantics or relationship to related search/get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' field is tautological ('Get Posts by IDs'), but the 'Do not use when' section offers real guidance: avoid when exploring, and prefer x_schema_discovery or x_query_suggestion. It also lists prerequisite/follow-up tools. Missing is explicit comparison to x_api_get_posts_by_id or search endpoints, so usage guidance is incomplete.
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?
With no annotations provided, the description carries full burden. It discloses read-only risk, required OAuth scopes (bookmark.read, tweet.read, users.read), environment-selection behavior for auth resolution, expected response shape, common failure conditions including rate limits, and safety warnings about sensitive data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Risk, Permissions, Environment, Parameters, Response, Failures, Tools, Safety, Example) but has redundancy: 'Get Bookmarks by folder ID' appears in both the first sentence and 'Use when', and read-only is mentioned in both Risk and Safety. It is somewhat verbose but structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers many contextual aspects: response shape, common failure conditions, auth prerequisites, and recommended tools. However, parameter semantics are incomplete, and the example is flawed by omitting a required parameter. Given 8 parameters and no output schema, this is only moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 8 parameters with 0% description coverage. The description only names id and folder_id with 'path, unknown, required' without explaining their actual meaning. It partially explains scopeTenantId/scopeUserId/scopeAccountId/credentialKey in environment-selection behavior, but omits authorizationKey and preferredAuthType entirely. The example also incorrectly omits the required folder_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Bookmarks by folder ID' which is a specific verb+resource+scope statement. It clearly distinguishes this tool from sibling tools like x_api_get_users_bookmarks (all bookmarks) and x_api_get_users_bookmark_folders (list folders).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is a tautological restatement of the purpose. The 'Do not use when' provides some exclusions (exploration, needing auth/config tools first) and recommends x_schema_discovery or x_query_suggestion, but it does not explicitly compare to sibling bookmark-fetching tools (e.g., x_api_get_users_bookmarks).
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?
With no annotations, the description carries full burden, and it discloses read-only status, required OAuth scopes, and the environment-selection behavior involving scopeTenantId, scopeUserId, and scopeAccountId. It also lists common failure conditions and safety warnings about sensitive data, which goes beyond simple annotations. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into labeled sections, making it scannable, and it includes a wealth of context (failure conditions, example, safety). However, it contains redundancy, such as 'Get Users by usernames.' and 'Use when: Get Users by usernames.' and a long 'Recommended prerequisite and follow-up tools' list that could be trimmed. The example also omits the required 'usernames' parameter, undermining its clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides a detailed response shape, common failures, and auth prerequisites, which is valuable. However, it fails to document all parameters (authorizationKey, preferredAuthType) and the example lacks the required 'usernames' field, leaving gaps for an agent to invoke correctly. The response shape is generic but acceptable for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains usernames (query, array, required) and the auth/environment parameters via the 'Environment-selection behavior' section (scopeTenantId, scopeUserId, scopeAccountId, credentialKey). However, it does not explain authorizationKey or preferredAuthType, and 'Parameter formats and constraints' only lists usernames, leaving several parameters underdocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Users by usernames,' identifying the operation and key parameter. It distinguishes from sibling tools like x_api_get_users_by_ids and x_api_get_users_by_username by indicating plural username lookup, though the 'Use when' section repeats the same phrase without adding differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance, advising against use when auth/configuration tools are needed or when exploring, and recommending x_schema_discovery or x_query_suggestion instead. However, the 'Use when' section is tautological ('Get Users by usernames') and does not compare to close siblings like x_api_get_users_by_ids or x_api_get_users_by_username. Prerequisite and follow-up tools are listed, but the primary condition is not well specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating 'Risk: read-only,' required OAuth scopes, environment-selection behavior, common failure conditions, and a safety warning about sensitive data. This is a thorough disclosure, though it does not cover every nuance (e.g., pagination behavior), leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections (Use when, Risk, Required permissions, etc.), making it well structured and scannable. It is lengthy but each section contributes meaningful information for a complex tool. It could be tightened, but the structure helps compensate for the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides expected response shape, common failure conditions, prerequisites, and environment-selection behavior, which is good for a tool with no output schema. However, it lacks complete parameter semantics for all 9 parameters and does not fully describe the result data. Given the tool's complexity, the description is not fully complete, so a score of 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only documents formats/constraints for query, state, and max_results, and briefly describes environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. Several parameters (authorizationKey, preferredAuthType) are not explained, and no defaults or complete behaviors are given. This is a significant gap for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search Spaces.', which clearly identifies the action (Search) and resource (Spaces). However, it does not elaborate on what kind of search (e.g., keyword, title) or otherwise distinguish from sibling search tools like x_api_search_communities or x_api_search_news, so it is clear but not strongly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when:' and 'Do not use when:' guidance, including specific alternatives such as x_schema_discovery or x_query_suggestion. It also names recommended prerequisite tools, giving the agent clear direction on when this tool is appropriate versus 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?
With no annotations, the description must carry the full burden of behavioral disclosure. 'Return' implies a read-only operation, but it doesn't explicitly state that there are no side effects, nor does it mention authentication requirements, rate limits, or potential errors. The list of returned information adds some transparency, but it is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that lists all information categories without redundancy or unnecessary detail. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description enumerates what the tool returns, but terms like 'inventory source' and 'auth-gate state' are not defined, and no return format is mentioned. Given the lack of an output schema, this introduces some ambiguity, but the overall context is adequate for a zero-parameter diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to explain. The description adds value by detailing the output categories, which is the relevant semantic content for this tool. Baseline 4 applies for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Return' and enumerates the exact categories of information (runtime metadata, inventory source, Postgres/Vault connection settings, auth-gate state), clearly distinguishing it from siblings like x_health_check or x_config_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as x_health_check or x_config_get. The description only states what it returns, with no mention of use cases or 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?
With no annotations, the description fully carries the transparency burden. It discloses mutating/high-risk status, required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings, providing exceptional visibility into the tool's behavior and consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized with labeled sections (Risk, Required permissions, Environment-selection, Parameters, Expected response, Common failures, Recommended tools, Safety, Example). The redundant 'Use when: Add Conversation Keys' line adds noise, but overall the structure is clear and each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, no annotations, no output schema), the description is remarkably complete. It includes permissions, environment selection, parameter constraints, response shape, failure modes, safety warnings, and an example. While it doesn't define 'conversation keys' or the exact body contract, it provides a robust operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It covers id (path/required), body (payload), and the scopeTenantId/scopeUserId/scopeAccountId/credentialKey selection behavior, but fails to explain authorizationKey and preferredAuthType. This partial coverage leaves gaps for a tool with 8 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Add Conversation Keys' which is a clear verb+resource, but it essentially restates the tool name without explaining what conversation keys are or how they differ from sibling tools like x_api_add_user_public_key. It lacks a specific behavioral definition or API endpoint context, making the purpose somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' (though tautological) and 'Do not use when' guidance, suggesting x_schema_discovery or x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools, offering clear context for when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility and excels. It clearly states read-only risk, required bearer token, environment-selection behavior for scoped credentials, parameter constraints, expected response shape, common failure conditions, and safety warnings. This is rich, actionable context beyond the bare description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Required permissions, etc.) and each section provides useful information. It is somewhat lengthy but avoids redundancy; the front-loaded 'Get subscriptions' is immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, this description is remarkably complete. It covers authorization, environment selection, parameter formats, response shape, failure conditions, and safety, providing all essential context an agent needs to invoke the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the role of key parameters: webhook_id (path, required), scopeTenantId combined with exactly one of scopeUserId/scopeAccountId for auth resolution, and credentialKey for selecting a stored profile. It leaves authorizationKey and preferredAuthType undocumented, but the major semantics are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get subscriptions' with a clear verb and resource, but it is vague about the specific type of subscriptions (account activity) and does not distinguish it from sibling tools like x_api_get_activity_subscriptions. The name itself provides more specificity than the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Use when' and 'Do not use when' clauses, providing context for when to avoid the tool (exploration, need for auth/config). However, it does not explicitly differentiate when to use this tool over other subscription-related tools, leaving ambiguity among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It clearly states read-only risk, required OAuth scopes, environment-selection behavior for credentials, expected response shape, common failure conditions, and safety warnings about sensitive data. This is thorough behavioral disclosure beyond what the schema conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections covering many aspects, which aids scanning. It earns its length mostly, but the 'Use when' section is a tautological waste and there is overlap between 'Risk' and 'Safety warnings.' Overall it is well-structured but not perfectly lean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 11 parameters, no annotations, and no output schema, the description provides extensive context: purpose, prerequisites, environment behavior, parameter formats, response shape, failures, recommended tools, safety, and an example. Minor gaps remain for optional authentication parameters, but overall it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the parameter section is essential. It adds query-location and requiredness for the five API parameters, and the environment-selection paragraph explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, authorizationKey and preferredAuthType are not described, leaving a gap for optional auth parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get historical Post insights,' a specific verb+resource statement. It clearly identifies the tool's function but does not explicitly distinguish it from sibling tools like x_api_get_insights28_hr or x_api_get_posts_analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line merely repeats the purpose ('Get historical Post insights') and provides no contextual trigger or comparison to alternatives. Although the 'Do not use when' line offers some exclusions for auth/config prerequisites and exploration, no positive usage conditions are conveyed.
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?
No annotations are provided, so the description carries the full burden and handles it thoroughly. It states read-only risk, required auth tokens and scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This is exemplary disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear labeled sections and packs in valuable detail without being overly verbose. The main redundancy is the 'Use when: Get Media by media keys' line, which adds no information beyond the first sentence. Overall, it is well-structured and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description supplies expected response shape, failure modes, prerequisites, and environment-selection behavior, which is strong coverage. It is not fully complete because it omits semantics for two parameters and does not explain how media_keys are typically obtained, but it covers most critical operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains media_keys as a required query array and clarifies the auth-related roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, authorizationKey and preferredAuthType are not described at all, leaving gaps for two of the seven parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Media by media keys' with a specific verb and resource. It does not explicitly differentiate from the closely named sibling x_api_get_media_by_media_key, but the plural 'media_keys' makes the intended operation reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the purpose ('Get Media by media keys') rather than giving concrete scenarios. The 'Do not use when' section provides some useful exclusions, such as preferring x_schema_discovery or x_query_suggestion when exploring, but it does not explain when to choose this tool over the singular media key sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It explicitly states 'Risk: read-only', outlines required permissions (OAuth scopes), describes environment-selection behavior (scopeTenantId plus exactly one of scopeUserId/scopeAccountId), lists common failure conditions, includes a safety warning about sensitive data, and provides the expected response shape. This is comprehensive and goes beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use when, Risk, Required permissions, etc.), making it scannable. It is somewhat verbose and repeats 'Get liked Posts' in the Use when section, but every other section adds meaningful context. The example is a helpful addition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no annotations, and no output schema, the description covers a lot: expected response shape, failure conditions, auth prerequisites, environment selection, and an example. It omits details on certain parameters (authorizationKey, preferredAuthType) and pagination behavior, but overall provides enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 9 parameters but the description only covers 3 (id, max_results, pagination_token) and partially explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. It does not explain authorizationKey or preferredAuthType. Given the 0% schema description coverage, the description compensates significantly for some parameters but leaves others unexplained, so a middle score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get liked Posts' which clearly identifies the action and resource, but it lacks specificity on whose liked posts are retrieved (the user ID is implied by the 'id' parameter). It does not explicitly distinguish from the sibling tool x_api_get_posts_liking_users, which performs the inverse operation. The tool name provides some clarity, but the description could be more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is tautological ('Get liked Posts'), providing no additional guidance. However, the 'Do not use when' section advises users to prefer x_schema_discovery or x_query_suggestion when exploring, and mentions prerequisites. It does not offer clear guidance on when to use this tool over other X API tools with similar read-only behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly states the operation is read-only, lists required auth scopes, describes environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This far exceeds the minimum and provides rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, making it easy to scan. It is longer than necessary in places (e.g., repeating 'Get owned Lists'), but every major section adds value. It is not as concise as ideal, but the structure earns it a strong score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, no annotations, no output schema), the description is quite comprehensive. It covers response shape, failure conditions, auth prerequisites, environment selection, and safety. However, it could elaborate on pagination_token behavior and max_results boundaries, and id is marked 'unknown' despite schema showing a string, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its 9 parameters, and the description partially compensates by explaining format/constraints for id, max_results, and pagination_token, plus the environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it leaves authorizationKey and preferredAuthType without explanation, and max_results semantics are incomplete (integer but no range or purpose).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get owned Lists' with a specific verb and resource, which is clear. However, it does not explicitly distinguish from sibling tools like x_api_get_users_followed_lists or x_api_get_lists_by_id, despite the name hinting at the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Use when' and 'Do not use when' sections, but the 'Use when' is tautological ('Get owned Lists'). The 'Do not use when' provides some context (exploration/auth tools) and recommends prerequisites, but it does not clearly contrast with alternative list-related tools. This is adequate but not fully explicit.
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?
With no annotations, the description covers safety (read-only), auth prerequisites (bearer token), environment-selection behavior, response shape, common failure conditions, and safety warnings. This fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with labeled sections and an example; no significant dead weight except the redundant 'Use when' repeat. Slightly long but each section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides response shape, failures, prerequisites, and an example, making it actionable. Lacks explanation of what stream links are and how they relate to webhook setup, so it is not a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains scopeTenantId/scopeUserId/scopeAccountId selection and credentialKey profile, but does not describe authorizationKey or preferredAuthType, and the 'Parameter formats and constraints' section only says 'no endpoint-specific parameters.' Compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get stream links,' a clear verb+resource that signals a retrieval operation. However, it never explicitly mentions 'webhooks' beyond the tool name, and the 'Use when' line is tautological, so it doesn't fully distinguish itself from sibling webhook tools beyond the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit 'Do not use when' with alternatives for exploration and auth configuration, but the 'Use when: Get stream links' is tautological and gives no context for choosing this over sibling webhook tools like x_api_get_webhooks or x_api_create_webhooks_stream_link. Guidance is only partial.
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?
With no annotations, the description carries the full burden and does so thoroughly. It discloses read-only status, required auth tokens and scopes, environment-selection behavior, common failure conditions, and safety warnings about sensitive data. This goes well beyond a basic 'read-only' label.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections (Use when, Risk, Required permissions, Parameter formats, etc.). It is lengthy but justified given 15 parameters and no annotations. Some redundancy exists, e.g., read-only mentioned twice, but overall it is organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes expected response shape, failure conditions, permissions, environment-selection behavior, and an example, making it quite complete for a tool without an output schema. Gaps remain: it does not define the 'recent' window or explicitly compare with x_api_search_posts_all.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameter formats and constraints, adding 'query' location and requiredness beyond the schema. However, it does not explain the meaning of parameters like start_time, since_id, or pagination_token, and omits some auth-related parameters from the list. With 0% schema coverage, this is partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search recent Posts,' which clearly identifies the verb and resource. It distinguishes from x_api_search_posts_all via the 'recent' qualifier, but does not explicitly name the sibling or define what 'recent' means, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a 'Do not use when' section recommending x_schema_discovery or x_query_suggestion for exploration, and lists prerequisite/follow-up tools. However, the 'Use when' is tautological ('Search recent Posts'), and there is no explicit direction to use x_api_search_posts_all for full-archive searches.
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?
With no annotations provided, the description carries the full burden and delivers: risk level ('read-only'), environment-selection behavior for scopes/credentials, expected response shape, common failure conditions, and safety warnings about sensitive data. It goes beyond the structured data by explaining how Vault/Postgres principal resolution works and what response structure to expect. This is exemplary transparency for a complex API tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with labeled sections, making it scannable and front-loaded with the primary purpose. Each section is concise, though the 'Use when' line is redundant with the first sentence. Overall, it packs substantial information into a readable format without excessive wordiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no annotations, and no output schema, the description covers a wide range of context: purpose, auth requirements, environment selection, response shape, failure conditions, safety, and an example. The primary gap is incomplete parameter semantics, but the breadth of behavioral and environment context compensates for much of the missing detail. It is a thorough description that would enable an agent to invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents only 3 of 9 parameters (backfill_minutes, start_time, end_time) and mentions scope/credential behavior in prose, but leaves authorizationKey and preferredAuthType unexplained. With 0% schema description coverage, the description fails to compensate for the missing parameter semantics, leaving the agent with incomplete knowledge for critical auth-related fields. The environment-selection section adds some context but is not a substitute for per-parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream Likes compliance data,' a specific verb+resource that clearly names the tool's function. It doesn't explicitly distinguish from similar streaming tools like firehose/sample variants, but the compliance term and tool name provide enough differentiation. The purpose is clear and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, including a preference for exploration tools like x_schema_discovery or x_query_suggestion. It also lists recommended prerequisite and follow-up tools, giving the agent a clear workflow context. However, it doesn't compare directly to sibling streaming tools, leaving some ambiguity about when compliance streaming is preferred over firehose/sample.
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?
With no annotations, the description carries the full transparency burden. It explicitly discloses mutating/high-risk behavior, required OAuth scopes, environment-selection behavior, common failure conditions, expected response shape, and a safety warning. This is far more comprehensive than typical tool descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Permissions, etc.), making it easy to scan and front-loaded with the core purpose. It is somewhat long, but every section provides useful context. The 'Use when' section is redundant, but overall the structure earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description is unusually complete: it covers expected response shape, prerequisites, failure conditions, environment selection, and provides a concrete example. The main gaps are incomplete semantics for some parameters and lack of detailed follow/unfollow edge cases, but this is still a very strong description for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially does: it explains that scopeTenantId plus exactly one of scopeUserId/scopeAccountId selects the tenant principal, and that credentialKey selects a non-default profile. It also lists source_user_id and target_user_id as path parameters. However, authorizationKey and preferredAuthType are not explained, and the 'unknown' type for required parameters is vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Unfollow User' as a specific verb+resource. However, it does not explicitly differentiate from sibling tools like x_api_follow_user or x_api_unmute_user, relying primarily on the tool name for distinction. The 'Use when: Unfollow User' line is a tautology that adds no new meaning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'Do not use when' clause, advising against exploration and preferring x_schema_discovery or x_query_suggestion first. However, the 'Use when' is simply 'Unfollow User'—a tautology—and there is no explicit comparison to alternative follow/unfollow or mute tools. The guidance is present but not deeply informative.
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?
With no annotations, the description fully carries the burden. It discloses mutating/high-risk behavior, required OAuth scopes, environment-selection semantics, common failure modes, and a safety warning. This is comprehensive and goes well beyond a simple summary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured with clear section labels. It front-loads the core purpose and each sentence provides useful information, though the 'Use when' section could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no output schema, and no annotations, the description is remarkably complete. It covers purpose, usage boundaries, risk, permissions, environment behavior, parameter hints, expected response, failure conditions, prerequisites, and an example, leaving little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains id as a path parameter, body as the payload, and clarifies the roles of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey. However, authorizationKey and preferredAuthType are not mentioned, leaving some parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Add public key', a clear verb+resource pair that identifies the action and target. It is distinct from sibling getter tools like x_api_get_users_public_key, though it does not elaborate on what adding a public key entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' is tautological ('Add public key'). The 'Do not use when' provides some context (prefer discovery when exploring, use auth tools first) but does not name specific alternative tools for the same operation, making it only moderately useful.
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?
With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly states the tool is 'mutating, high-risk', requires OAuth 2 user token with media.write or OAuth 1a user token, explains environment-selection behavior via scopeTenantId and scopeUserId/AccountId, describes expected response shape, lists common failure conditions, and includes safety warnings. This is comprehensive and transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections. Most sentences provide useful details, but the 'Use when: Initialize Chat Media Upload' is redundant filler that restates the tool's name. The overall structure is effective, though trimming tautological parts would improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with 7 parameters and no output schema, the description is quite complete: it covers purpose, usage boundaries, permissions, auth selection, response shape, failure modes, and safety. The main gap is the lack of explicit connection to the subsequent steps in the chat media upload flow (x_api_chat_media_upload_append, x_api_chat_media_upload_finalize), which would be valuable contextual information. Overall, it is robust but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution, and states that body is the request payload. However, it does not explain authorizationKey or preferredAuthType, leaving some parameters under-explained. It adds significant value but not complete parameter coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function as 'Initialize Chat Media Upload.' However, it does not explicitly distinguish this from sibling tools like x_api_initialize_media_upload, which appears to be a similar non-chat media upload initializer. The purpose is clear but not differentiated from likely similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause recommending x_schema_discovery or x_query_suggestion for exploration, and lists prerequisite/follow-up tools. However, the 'Use when' section is a tautology ('Initialize Chat Media Upload') and does not provide specific guidance on when to use this tool over x_api_initialize_media_upload or how it fits with x_api_chat_media_upload_append/finalize. The guidance is present but not sufficiently specific to the tool's actual workflow.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states risk (read-only), required permissions (bearer token), environment-selection behavior (scopeTenantId plus exactly one of scopeUserId/scopeAccountId), expected response shape, common failure conditions, and safety warnings about sensitive data. This is exceptionally transparent for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Environment-selection behavior, etc.), making it easy to scan. It is longer than average, but most sentences provide valuable context. The redundancy of 'Use when: Get subscription count' repeats the first line and wastes a sentence, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema and annotations, the description is remarkably complete. It covers purpose, usage guidance, permissions, environment selection, parameter constraints, response shape, failure conditions, recommended tools, safety warnings, and an example. The only minor gaps are the two unexplained parameters, but overall it provides sufficient context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, but the statement 'no endpoint-specific parameters' is misleading given the schema lists six parameters. It also leaves authorizationKey and preferredAuthType completely unexplained. The example illustrates scopeTenantId and scopeUserId, but semantic coverage is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get subscription count' with a specific verb and resource. However, it does not explicitly distinguish itself from sibling tools like x_api_get_account_activity_subscriptions (plural), which likely lists subscriptions rather than counting them. The name itself helps, but the description could be more explicit about the count vs. list distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Use when' and 'Do not use when' guidance, but the 'Use when' is tautological ('Get subscription count'). It does offer useful exclusions (e.g., prefer x_schema_discovery or x_query_suggestion when exploring) and recommends prerequisite/follow-up tools like x_connection_info and x_auth_get_scope_credentials. However, it does not compare this tool against sibling subscription tools, leaving some ambiguity about when to choose this over x_api_get_account_activity_subscriptions.
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?
With no annotations present, the description carries the full burden and excels at it. It discloses the read-only risk, required permissions (bearer token, OAuth 2/1a scopes), environment-selection behavior for scope parameters, common failure conditions, and safety warnings about sensitive account data. This provides rich behavioral transparency beyond a simple operation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections (Risk, Required permissions, Environment-selection behavior, etc.). It front-loads the purpose and avoids fluff—every section adds concrete value. While it could be trimmed slightly, the structure compensates for length and aids parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and no annotations, the description is remarkably complete. It includes expected response shape, common failure conditions, recommended tools, an example invocation, and safety warnings. This gives an agent enough context to select and invoke the tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does explain the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in authentication selection, and specifies types for max_results and pagination_token. However, it omits semantics for authorizationKey and preferredAuthType, leaving a noticeable gap in parameter coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Get X activity subscriptions.' However, it does not explicitly distinguish itself from sibling tools like x_api_get_account_activity_subscriptions or x_api_get_activity_subscription_count. The 'Use when' line merely repeats the purpose without adding differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context through 'Do not use when' (e.g., preferring x_schema_discovery or x_query_suggestion for exploration) and recommends prerequisite tools like x_connection_info and x_auth_get_scope_credentials. However, the 'Use when' is tautological and there is no explicit guidance on when to choose this tool over its sibling subscription-related 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?
With no annotations available, the description carries the full burden and does so thoroughly. It clearly states 'Risk: read-only', lists required OAuth scopes, explains environment-selection behavior for auth resolution, details common failure conditions (missing credentials, rate limits, etc.), and warns about sensitive data exposure. This exceeds typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it easy to scan. It is front-loaded with purpose and risk. Some redundancy exists ('Use when' repeats the purpose), but overall each section adds meaningful information without excessive fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex tool with 10 parameters, no output schema, and no annotations. The description provides a comprehensive picture: expected response shape, common failure conditions, recommended prerequisites, environment-selection behavior, safety warnings, and an example. It covers almost every aspect an agent needs to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema coverage, the description partially compensates by listing key parameters (id, max_results, pagination_token, event_types) with types and location. It also explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in prose. However, it omits authorizationKey and preferredAuthType, and does not fully explain the semantics of each parameter beyond basic type/location.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get DM events for a DM conversation.' It names the resource and action. However, it does not explicitly distinguish itself from sibling tools like x_api_get_direct_messages_events_by_participant_id, relying on the tool name for the 'by_conversation_id' distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is tautological, merely repeating the purpose. The 'Do not use when' guidance is useful for directing exploration to x_schema_discovery or x_query_suggestion, but it does not address when to use this tool over alternative DM event retrieval tools. It does mention prerequisites and recommended companion tools, which adds some 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?
With no annotations, the description carries full burden and does so thoroughly: it declares read-only risk, lists required OAuth scopes, explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, and notes common failure conditions and the possibility of sensitive data in responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded with the main purpose. However, the 'Use when: Get DM events for a DM conversation' line is redundant with the first sentence, wasting space that could have been used for sibling differentiation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description provides the expected response shape, common failure conditions, prerequisites, and an example. It is missing details about pagination token usage and event_types allowed values, but for a complex tool with 10 parameters it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by providing parameter formats for participant_id, max_results, pagination_token, and event_types. It also explains the meaning of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in the environment-selection section, but leaves authorizationKey and preferredAuthType unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get DM events for a DM conversation' which clearly indicates the action and resource. However, it does not mention 'by participant ID' from the tool name, failing to distinguish it from sibling tools like x_api_get_direct_messages_events_by_conversation_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section is tautological, merely repeating the description. The 'Do not use when' provides a general exploration alternative (x_schema_discovery, x_query_suggestion) but does not clarify when to choose this tool over other DM event retrieval siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly states 'Risk: read-only', lists required permissions and prerequisites, describes environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This is thorough and goes well beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections and front-loaded with the purpose. It packs a lot of useful information. Minor redundancy exists ('Get List followers' appears in both the opening and 'Use when'), causing slight waste, but overall it is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description compensates with an expected response shape. It also covers auth prerequisites, environment-selection behavior, failure conditions, recommended companion tools, and an example. This makes the tool contextually complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It partially does by listing parameter formats for id, max_results, and pagination_token, and explaining scopeTenantId/scopeUserId/scopeAccountId/credentialKey behavior. However, authorizationKey and preferredAuthType are not described in the prose, and no details are given for max_results bounds or pagination_token usage, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get List followers', which is a clear verb+resource statement. It identifies the tool's function as retrieving followers of a list, distinguishing it from sibling tools like x_api_get_lists_members or x_api_get_lists_posts. However, it lacks an explicit scope statement (e.g., 'returns the users who follow a given list'), so it is not fully specific on its own.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Use when: Get List followers' and 'Do not use when... prefer x_schema_discovery or x_query_suggestion first', which gives clear guidance for exploration and auth-config cases. However, it does not offer comparative guidance against related list tools (e.g., when to use x_api_get_lists_members instead), so usage context is only partially explicit.
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?
No annotations are provided, so the description carries the full burden. It explicitly declares 'Risk: read-only', details required OAuth scopes, explains environment-selection behavior, lists common failure conditions, and provides the expected response shape. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loads the core purpose. However, it contains redundancy: 'Use when' repeats the first sentence, and 'Risk: read-only' overlaps with the safety warning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers all major decision-making aspects: purpose, usage conditions, permissions, auth resolution, parameter formats, expected response, failure modes, and recommended companion tools. It is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description partially compensates by explaining media_id, command, and the environment-selection parameters. However, it leaves authorizationKey and preferredAuthType unexplained, and the 'media_id (query, unknown, required)' format is unhelpful with 'unknown' type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Media upload status' with a specific verb and resource. It distinguishes the tool from media upload lifecycle tools by focusing on status, but does not explicitly name sibling tools, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides 'Use when' and 'Do not use when' sections, but 'Use when' merely restates the purpose. The 'Do not use when' guidance is generic and does not compare with direct alternatives like x_api_get_media_by_media_key or x_api_media_upload. It mentions exploration tools but lacks tool-specific exclusion context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It explicitly states read-only risk, required OAuth scopes, common failure conditions (rate limits, auth failures), expected response shape, and safety warnings about sensitive account data. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections (Risk, Permissions, Parameter formats, etc.) and is information-dense without excessive fluff. The 'Use when: Get Liking Users' is a redundant tautology, but overall structure earns a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers permissions, response shape, failure conditions, safety, and an example, which is strong for a complex tool with no output schema. However, it does not explicitly clarify that 'id' is the post ID or explain pagination_token mechanics, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the crucial environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and lists constraints for id, max_results, and pagination_token. However, it omits authorizationKey and preferredAuthType, leaving some parameters under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Liking Users' with a specific verb and resource, and the tool name reinforces this. However, it does not differentiate from closely related sibling tools like x_api_get_users_liked_posts, so it lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section simply repeats 'Get Liking Users' with no added context. The 'Do not use when' provides general advice to prefer discovery tools first, but it does not compare against specific alternative API tools for the same operation, leaving usage guidance partially implied.
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?
No annotations are provided, but the description thoroughly covers behavior: read-only risk, required permissions (bearer token, OAuth 2 with scopes, OAuth 1a), environment-selection behavior for auth resolution, common failure conditions, response shape, and safety warnings. This is comprehensive given the tool's complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded with the purpose. However, it contains redundancy ('Use when: Get User by ID' repeats the opening line) and the parameter format line is ambiguous ('unknown' type), preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers auth, environment selection, failure modes, response envelope, and provides an example. It omits details on authorizationKey and preferredAuthType semantics, and the expected response shape does not clarify the shape of the actual user data, but overall it provides substantial context for a 7-parameter tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains id (path, required), scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in the environment-selection behavior, covering 5 of 7 parameters. However, authorizationKey and preferredAuthType are not explained in the description, and the schema provides no descriptions (0% coverage), so the agent has incomplete guidance for these optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get User by ID' with a specific verb and resource. However, it does not differentiate from sibling tools like x_api_get_users_by_ids or x_api_get_users_by_username, and the 'Use when' clause repeats the tool name without adding distinguishing context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause directing agents to x_schema_discovery or x_query_suggestion for exploration, and mentions prerequisite tools. However, the 'Use when' is tautological ('Get User by ID'), and there are no explicit alternatives for similar user-retrieval tools, making guidance only partially clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does exceptionally well. It discloses read-only risk, required permissions (bearer token, OAuth scopes), environment-selection behavior, common failure conditions, and safety warnings about sensitive data. This goes far beyond a simple read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it contains redundancy: 'Get User by username' appears in both the opening and 'Use when', and the read-only property is stated twice. While the length is justified by the amount of context, tighter wording would improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers a lot: required permissions, environment behavior, expected response wrapper shape, common failures, and an example call. The inner 'data' object is not detailed (e.g., user fields), but the overall envelope is specified, and the recommendation of prerequisite tools fills additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the required 'username' parameter and clarifies the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment selection. However, authorizationKey and preferredAuthType are not described, leaving some parameters semantically unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Get User by username.' This clearly identifies the resource and operation. However, it doesn't distinguish itself from the similar sibling tools x_api_get_users_by_usernames (plural) or x_api_get_users_by_id, relying on the name alone for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Do not use when' guidance, noting that exploration should prefer x_schema_discovery or x_query_suggestion, and that auth/configuration tools may be needed first. However, the 'Use when' section merely repeats the tautological purpose, and no explicit comparison is made to sibling user lookup tools, leaving a slight gap.
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?
No annotations are provided, but the description discloses read-only risk, required bearer token, environment-selection via scopeTenantId/scopeUserId/scopeAccountId, common failure conditions, and safety warnings about sensitive data. It does not describe the actual streaming semantics or the label data schema, but provides substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it scannable despite its length. Some redundancy exists ('Risk: read-only' followed by 'Safety warnings' that also states read-only), and the 'Use when' line is a tautology, but each section contributes useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes an example, failure conditions, recommended tools, and response shape, which covers most operational concerns for a complex 9-parameter tool with no output schema. It falls short by not specifying the structure of the label data payload and the exact behavior of the streaming connection, which is important for consumers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the roles of scopeTenantId, scopeUserId, scopeAccountId, credentialKey, and the formats of backfill_minutes, start_time, and end_time. However, authorizationKey and preferredAuthType are not mentioned, and constraints for time formats are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream Post labels,' providing a specific verb and resource that distinguishes it from sibling tools like x_api_stream_posts_compliance or x_api_stream_likes_compliance. However, it does not elaborate on what 'labels' are or how they relate to posts, and the 'Use when: Stream Post labels' line merely restates the purpose without adding clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit 'Do not use when... prefer x_schema_discovery or x_query_suggestion first' exclusion, and recommends prerequisites like x_connection_info and x_auth_get_scope_credentials. It lacks a direct comparison to other streaming tools, but the resource name sufficiently differentiates them.
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?
With no annotations, the description carries the full burden. It discloses read-only nature, bearer token requirement, environment-selection behavior, common failure conditions, and safety warnings about sensitive data. It falls short of detailing streaming mechanics but is otherwise thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections, making it easy to scan. Some redundancy ('Risk: read-only' vs 'Safety warnings: This is read-only') but no wasted sentences overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description provides extensive context: permissions, environment behavior, failure modes, response shape, and an example. The main gap is the incomplete parameter semantics, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It covers some parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) with behavioral context, and lists formats for four query params, but fails to explain the semantics of partition, start_time, end_time, and omits authorizationKey and preferredAuthType entirely. This is insufficient for a 10-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream Users compliance data,' a specific verb+resource that clearly distinguishes this tool from sibling tools like x_api_stream_posts_compliance and x_api_stream_likes_compliance. It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' guidance, including preferring x_schema_discovery or x_query_suggestion for exploration. However, it does not explicitly differentiate from other compliance stream tools, so it is not a perfect 5.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explicitly states 'Risk: mutating, high-risk', includes safety warnings about mutating X state, details required OAuth scopes, explains environment-selection behavior, and lists common failure conditions. This far exceeds the typical transparency level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections for risk, permissions, environment behavior, parameter formats, response shape, failure conditions, and example. The only redundancy is 'Use when: Unblock DMs' which merely restates the purpose. Overall, each section earns its place and the front-loaded one-liner gives immediate clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no annotations, no output schema), the description is remarkably complete. It provides the expected response shape, common failure conditions, required permissions, a detailed environment-selection explanation, and an explicit example. This gives an agent sufficient context to invoke the tool effectively without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the environment-selection parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) and notes that 'id' is a required path parameter. However, it leaves authorizationKey and preferredAuthType unexplained, and the format of 'id' is listed as 'unknown', providing only partial semantics for the seven parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Unblock DMs', which is a specific verb+resource statement that clearly identifies the action. It also implicitly distinguishes from the sibling tool 'x_api_block_users_dms' by being the inverse operation. However, it doesn't elaborate on what 'id' refers to (e.g., user ID) or provide additional context beyond the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when: Unblock DMs' is tautological and provides no new information. The 'Do not use when' clause gives generic exclusions (prefer x_schema_discovery or x_query_suggestion) but doesn't specify when this tool should be used over other mutation tools like x_api_request. Recommended prerequisite and follow-up tools are listed, which adds some 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?
With no annotations, the description carries the full burden and does well: it discloses mutating/high-risk nature, bearer token requirement, tenant/credential selection behavior, common failures, and safety warnings. However, the 'bearer token' prerequisite seems to conflict with the schema's preferredAuthType enum allowing OAuth types, and the exact mutation semantics (add/replace/delete) are not described, preventing a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and is dense with useful information. The redundant 'Use when: Update stream rules.' line wastes a bit of space, but every other sentence contributes. It is longer than the TDQS examples but justified by the absence of annotations and the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 9 parameters, the description is quite complete: it provides expected response shape, failure conditions, prerequisites, safety warnings, and an example. It lacks full parameter coverage (preferredAuthType) and does not explain the relationship to stream rule retrieval, but overall it covers the essential context well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains dry_run, delete_all, body, scopeTenantId, scopeUserId, scopeAccountId, and credentialKey reasonably well, but omits preferredAuthType and does not detail the body structure. The description adds meaning beyond the schema for most parameters, but not all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update stream rules', identifying the specific action and resource, which distinguishes it from getter tools like x_api_get_rules. However, the 'Use when' line repeats the same phrasing and adds no additional clarity, and the description does not elaborate on what 'update' entails beyond the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-not-to-use guidance, recommending x_schema_discovery or x_query_suggestion for exploration, and mentions when a more specific auth/configuration tool is needed. It also lists recommended prerequisite/follow-up tools. However, the 'Use when' is tautological and there is no direct comparison with rule-related tools like x_api_get_rules, so it falls short of a 5.
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?
No annotations are provided, so the description carries the full burden. The verb 'Search' implies a read-only operation, but the description does not disclose what the search returns, pagination, or any other behavioral details. This is a moderate gap for a discovery tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place. The first states the core function, the second gives usage context. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and usage timing, making it minimally viable for a discovery tool. However, the absence of any parameter descriptions and output information leaves the agent without guidance on how to craft searches or interpret results, given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the seven parameters (tags, limit, query, method, authType, mutating, includeCatalog). The parameter names are somewhat self-explanatory, but the description adds no specific semantics, so it fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Search the generated X API operation inventory', giving a specific verb and resource. It also distinguishes from the many sibling endpoint tools by positioning itself as a pre-call discovery step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use this before calling a dedicated X endpoint tool when you know the intent but not the exact operationId or parameter set', which provides clear when-to-use and implies the alternative (dedicated tools). This is strong 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?
With no annotations, the description carries the full burden, and it is exceptionally transparent. It discloses mutation risk, required OAuth scopes, environment-selection behavior, common failure conditions, and safety warnings. This far exceeds typical disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections, making details easy to scan. There is some redundancy between 'Risk: mutating, high-risk' and 'Safety warnings: This mutates X state,' but overall each section contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, absence of annotations, and minimal schema descriptions, the description is remarkably complete. It covers purpose, permissions, environment selection, parameter formats, response shape, failure conditions, recommended companion tools, and includes a concrete example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates well. It explains the roles of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in environment selection, and indicates that body carries the request payload. However, it does not explicitly describe preferredAuthType, leaving some parameters under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Community Note,' which is a specific verb+resource combination. It distinguishes implicitly from sibling tools like x_api_delete_community_notes, but does not explicitly call out alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides some usage guidance: 'Use when: Create a Community Note' is tautological, but 'Do not use when... prefer x_schema_discovery or x_query_suggestion first' gives an explicit exclusion for exploratory use. However, it lacks clear guidance on when to use this tool versus other note-related or creation 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?
No annotations are provided, so the description carries the full burden. It explicitly flags the tool as 'mutating, high-risk', requires a bearer token, explains environment-selection behavior, includes a safety warning about mutating X state, and lists common failure conditions. This is rich, useful behavioral disclosure beyond what the schema gives.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded with the core action. The 'Use when' line is redundant with the opening sentence, which wastes a small amount of space. The example and structured sections are valuable and earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating 7-parameter tool with no annotations or output schema, the description covers most critical aspects: purpose, risk, permissions, scope selection, response shape, failure conditions, follow-up tools, and an example. Gaps include missing semantics for authorizationKey and preferredAuthType, and no guidance on sibling deletion-tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clearly explains endpoint_id and the scoping/credential parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey). However, authorizationKey and preferredAuthType are not described, leaving two of seven parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Terminate connections by endpoint.' This clearly identifies the action and scope. It also distinguishes from sibling tools like x_api_delete_connections_by_uuids and x_api_delete_all_connections by the deletion criterion (endpoint).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' is tautological ('Terminate connections by endpoint' restates the purpose). The 'Do not use when' provides some exclusions for exploration and auth-config scenarios, but it does not explain when to prefer this over the two other connection-deletion tools. Guidance is partially useful but incomplete.
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?
With no annotations provided, the description carries full behavioral disclosure and delivers: read-only risk, required OAuth scopes (dm.read), environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This is comprehensive and exceeds the minimum needed to inform an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clearly labeled sections (Use when, Risk, Required permissions, etc.) and front-loads the core purpose. It is somewhat lengthy, and the first 'Use when' line redundantly restates the purpose, but each section provides actionable information and the structure aids quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, no annotations, no output schema), the description covers most critical aspects: auth prerequisites, environment-selection behavior, response shape, failure conditions, recommended tools, and an example. However, it omits explanations for some optional parameters and does not elaborate on the meaning of the required resource IDs, so it's not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the behavior of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment selection, but the required path parameters (dm_id, media_id, resource_id) are only listed as 'path, unknown, required' with no semantic meaning. Optional params like authorizationKey and preferredAuthType are left undocumented, leaving notable gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Download DM Media,' a specific verb+resource that clearly states the tool's function. The tool name itself differentiates it from chat media download and other media tools, but the description doesn't explicitly contrast with siblings like x_api_chat_media_download, so it's clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections, advising against using it for exploration and recommending x_schema_discovery or x_query_suggestion instead. It also lists recommended prerequisite and follow-up tools (x_connection_info, x_auth_get_scope_credentials, x_api_request), providing solid context for when this tool fits in a workflow.
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?
With no annotations provided, the description carries the full burden. It discloses read-only risk, required bearer token, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId/credentialKey, common failure conditions (missing credentials, rate limits), and safety warnings about sensitive data. This is substantial behavioral detail beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it contains redundancy: the opening line 'Get Connection History' is repeated in the 'Use when' section. The length is justified by rich detail, but the tautology could be removed for better conciseness. Overall it's readable and front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description compensates with an expected response shape, failure conditions, prerequisites, and a usage example. It doesn't explain pagination semantics or fully describe all parameters, but for a read-only history tool, it covers the essential operational context. The example is helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the semantics of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey via environment-selection behavior. However, for status, endpoints, max_results, and pagination_token, it merely lists their types without explaining their meaning or usage. authorizationKey and preferredAuthType are not mentioned at all, leaving gaps for 6 of 10 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Connection History,' which is a clear verb+resource statement. However, it doesn't explicitly differentiate from sibling x_connection_info, and the 'Use when: Get Connection History' is tautological. The rest of the description clarifies it's a read-only operation, but the core purpose is mostly a restatement of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Do not use when: a more specific auth/configuration tool is required before the API call or you are only exploring; prefer x_schema_discovery or x_query_suggestion first.' It also lists recommended prerequisite/follow-up tools, such as x_auth_get_scope_credentials and x_api_request. However, the 'Use when: Get Connection History' section is circular and doesn't add new usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and excels: it discloses read-only risk, required OAuth scopes, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId/credentialKey, common failure conditions, and safety warnings about sensitive data. This is far beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-organized into labeled sections, making it easy to scan. Minor redundancy exists ('Get DM event by ID' repeated in Use when, read-only repeated), but every section adds useful context for a tool with no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes expected response shape, common failure conditions, prerequisites, and auth behavior, which is strong given no output schema and no annotations. It does not explain the semantics of returned event data or detail all optional parameters, but it provides adequate context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and 7 params exist. The description explains event_id as required path and gives behavior context for scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in the environment-selection section, but it does not explain authorizationKey or preferredAuthType beyond the schema enum. Partial compensation for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get DM event by ID' clearly states the verb and resource, and the 'by ID' qualifier distinguishes it from sibling tools that fetch events by conversation, participant, or list. This directly clarifies the tool's 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Do not use when' clause for exploration/auth scenarios and recommends x_schema_discovery or x_query_suggestion. However, the 'Use when' clause merely restates the purpose and does not mention alternative sibling tools for fetching DM events by conversation/participant, leaving comparative guidance incomplete.
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?
With no annotations, the description carries full responsibility and excels. It declares read-only risk, required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This goes far beyond basic transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections, making it scannable. The 'Use when' section is redundant and could be omitted, but all other sections provide meaningful information. It is appropriately detailed for a complex API tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers purpose, usage, permissions, params, response shape, failures, and safety. It does not explain what '28-hour insights' means in detail nor fully document all optional parameters, but overall it is solid and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the three required parameters (tweet_ids, granularity, requested_metrics) and clarifies the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, authorizationKey and preferredAuthType are not explained, leaving gaps for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get 28-hour Post insights', which identifies the resource and action. However, it does not differentiate from sibling tools like x_api_get_insights_historical or x_api_get_posts_analytics, making the scope slightly ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' sections, including guidance to prefer x_schema_discovery or x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools. However, the 'Use when' is tautological and does not offer alternative tools for similar insights.
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?
No annotations are provided, so the description carries full behavioral burden. It explicitly declares read-only risk, required bearer/OAuth tokens and scopes, explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, and lists common failure conditions and safety warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections that are easy to scan and front-loaded with the core purpose. Some redundancy exists, such as 'Use when: Get Media by media key' and 'Risk: read-only', but the length is justified by the detailed auth, failure, and response information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description provides a complete picture: expected response shape, auth prerequisites, failure conditions, environment-selection behavior, safety notes, and an example call. This is more than sufficient for an agent to decide when and how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for any of the 7 parameters, so the description must compensate. It identifies media_key as a required path parameter and clarifies scopeTenantId/scopeUserId/scopeAccountId/credentialKey in the environment-selection section. However, authorizationKey and the preferredAuthType enum are not explicitly explained beyond the auth prerequisites.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Media by media key' with a specific verb and resource, matching the tool name. It does not explicitly differentiate from the sibling x_api_get_media_by_media_keys, though the singular 'media key' hints at the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the tool name, providing no concrete use-case context. The 'Do not use when' section gives generic exploration guidance and recommends x_schema_discovery or x_query_suggestion, but it does not compare with media-specific alternatives like the plural media-keys tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses read-only risk, required bearer token, environment-selection behavior for scoping parameters, expected response shape, common failure conditions, and safety warnings about sensitive data. This is comprehensive behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded with a clear one-line purpose. Some redundancy exists between the opening sentence and the 'Use when' section, but overall the content is organized and avoids excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description provides the expected response shape, failure conditions, prerequisites, an example, and safety warnings. It also references related tools for context. This is a complete guide for using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the role of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in auth resolution, but does not elaborate on authorizationKey or preferredAuthType. The statement 'no endpoint-specific parameters' is vague and adds limited value. Partial compensation for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose as 'Get stream rule counts' with a specific verb and resource. While the name and description are nearly identical, the resource is clear and distinct from sibling rule tools like x_api_get_rules. No explicit differentiation from alternatives, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a 'Use when' section that directly restates the purpose and a 'Do not use when' that advises against exploratory use, suggesting x_schema_discovery or x_query_suggestion instead. It also lists recommended prerequisite and follow-up tools, giving practical context for when this tool fits in a workflow.
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?
With no annotations provided, the description carries the full burden of disclosing behavior. It states 'Risk: read-only,' lists required OAuth scopes, describes the scoped credential resolution logic, gives the expected response shape, common failure modes, and a safety warning about sensitive account data. This is comprehensive and goes well beyond a simple read-only note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but divided into labeled sections (Use when, Do not use when, Risk, Required permissions, etc.), which aids parsing. The only redundancy is the 'Use when: Get Space Posts' line, which restates the first sentence; otherwise, each section adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description provides a thorough operational picture: it covers permissions, environment-selection behavior, parameter formats, expected response shape, failure conditions, safety, and a concrete usage example. It does not explain all authentication parameters, but for a GET endpoint this is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is 8 parameters with 0% coverage in the description, so the description must compensate. It explicitly describes id and max_results formats, and the environment-selection behavior explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it does not explain authorizationKey or the preferredAuthType choices, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Space Posts,' which is a specific verb and resource, and the example clarifies it operates on a space id. However, it does not explicitly distinguish this from semantically close sibling tools like x_api_get_spaces_by_id or x_api_get_posts_by_id, so it lacks in-text sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' clause merely repeats the tool name ('Get Space Posts'), providing no additional context. The 'Do not use when' clause offers some useful exclusions (prefer x_schema_discovery or x_query_suggestion for exploration, and auth/config tools for setup), but it fails to mention when to choose this over other space- or post-related API 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states 'Risk: read-only,' required OAuth scopes, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId/credentialKey, common failure conditions, and a safety warning about sensitive data. This is rich, non-obvious behavioral context that goes well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Environment-selection, Parameter formats, Expected response, Common failures, Recommended tools, Safety, Example), making it easy to scan. The 'Use when: Get Bookmark folders' line is redundant with the first sentence, but otherwise every section earns its place and adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, yet the description provides an expected response shape, which is valuable. It also includes common failure conditions, prerequisites, and an example invocation. However, it does not fully explain the meaning of the id parameter or how pagination_token should be used across calls, leaving some ambiguity for a tool with 9 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes a parameter section listing id, max_results, and pagination_token, and explains the role of scopeTenantId/scopeUserId/scopeAccountId/credentialKey in environment selection. However, it omits authorizationKey and preferredAuthType, and the description of id simply says 'unknown,' providing no semantic clarity about what the id refers to. This partially compensates for low schema coverage but leaves significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Bookmark folders,' a specific verb+resource pairing that clearly identifies the tool's function. It does not explicitly differentiate itself from sibling tools like x_api_get_users_bookmarks_by_folder_id, but the resource term 'folders' is distinct enough to avoid confusion for most 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, and recommends prerequisite tools such as x_schema_discovery and x_query_suggestion when exploring. It also lists recommended follow-up tools, giving clear context on when to invoke this tool. However, it does not explain when to choose this over the sibling x_api_get_users_bookmarks_by_folder_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It explicitly states 'Risk: read-only,' required OAuth 2 scopes, environment-selection behavior, common failure conditions, and safety warnings about sensitive data. This is extensive behavioral disclosure beyond what a schema could provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear section headings and fronts the purpose, but contains minor redundancies such as 'Use when: Get Bookmarks' and repeated read-only mentions. The length is largely justified by the complexity, and every section serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes prerequisites, auth resolution behavior, expected response shape, common failure conditions, recommended tools, safety warnings, and an example. Given that there is no output schema and no annotations, this is a strong effort, though it could elaborate on pagination semantics and the remaining parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description covers parameter formats for id, max_results, and pagination_token, and explains environment-selection behavior for scopeTenantId, scopeUserId/AccountId, and credentialKey. However, it omits authorizationKey and preferredAuthType, and uses 'unknown' for the type of id and pagination_token, leaving some meaning unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Bookmarks,' a clear verb+resource statement that identifies the tool's function. It does not explicitly differentiate from sibling tools like x_api_get_users_bookmarks_by_folder_id, but the name and generic phrasing make the core purpose evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Do not use when' section that advises against using this tool when exploring or before auth/configuration, recommending x_schema_discovery or x_query_suggestion instead. It also lists prerequisite and follow-up tools, providing contextual guidance. However, it does not directly contrast with sibling bookmark tools, so it lacks complete exclusionary 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?
With no annotations provided, the description fully carries the transparency burden. It discloses read-only risk, required OAuth scopes and token types, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This is exemplary and goes well beyond basic requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and an example, making it easily scannable. It is verbose but mostly informative. Redundancy exists (e.g., 'Risk: read-only' and 'Safety warnings: This is read-only'), which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex API tool with no output schema and no annotations, the description provides a robust context: response shape, permissions, environment behavior, failure conditions, and an example. It lacks detailed semantics for all parameters and does not explain the contents of the returned data, but overall it is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains 'id' as a required path parameter and details the environment-selection roles of scopeTenantId/scopeUserId/scopeAccountId and credentialKey. However, it omits meaning for authorizationKey and preferredAuthType, leaving some parameters unclarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get pinned Lists' clearly, identifying the action and resource. It is specific enough to distinguish from sibling tools by its unique subject, but it does not explicitly differentiate from related list tools (e.g., x_api_get_users_followed_lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Use when' and 'Do not use when' guidance, explicitly recommending x_schema_discovery or x_query_suggestion for exploration. However, it does not suggest alternative tools for similar list-related operations, so it falls short of full when-not/alternatives coverage.
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?
With no annotations provided, the description carries the full burden. It discloses read-only risk, required OAuth scopes, environment-selection behavior, common failure conditions, and a safety warning about sensitive account data. This is comprehensive and goes far beyond what structured fields provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections with a front-loaded purpose and actionable details. The 'Use when: Get user public keys' line is redundant with the first sentence, but overall the structure is efficient and every other section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and 7 parameters, the description covers expected response shape, common failure conditions, required permissions, safety warnings, and an example invocation. An agent has sufficient information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains id as path/required, the scopeTenantId/scopeUserId/scopeAccountId selection logic, and credentialKey behavior. However, authorizationKey and preferredAuthType are not described, leaving some parameters under-explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get user public keys', which clearly states the verb and resource. However, it does not differentiate from the sibling tool x_api_get_users_public_keys (plural), and the wording 'keys' may conflict with the singular tool name. It is clear but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance with alternatives (x_schema_discovery, x_query_suggestion) and lists recommended prerequisite/follow-up tools. The 'Use when' line is tautological ('Get user public keys'), but the exclusions and context provide useful 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?
With no annotations, the description carries the full burden and does so thoroughly: it states read-only risk, required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This exceeds minimal disclosure and gives an agent a clear behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses clear labeled sections, making it scannable, and front-loads the core purpose. However, it repeats 'Get Reposts of me' in the Use-when line, and some boilerplate could be trimmed. Overall it is well organized and earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, zero annotations, and no output schema, this description is impressively complete: it covers auth prerequisites, environment/credential selection, response shape, failure conditions, and includes a concrete example. The agent can reasonably invoke this tool with high confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in the environment-selection section, but only mentions max_results and pagination_token with a vague 'unknown' for pagination_token, and does not address authorizationKey or preferredAuthType at all. This leaves real gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Get Reposts of me.' It indicates a specific endpoint for the authenticated user's reposts, distinguishing it from sibling tools like x_api_get_posts_reposts or x_api_get_posts_reposted_by. However, the phrase 'Reposts of me' is slightly ambiguous (reposts made by me vs. reposts of my content) and not disambiguated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line is tautological, but the 'Do not use when' section explicitly directs to alternatives like x_schema_discovery or x_query_suggestion for exploration and mentions needing auth/configuration tools first. It also lists recommended prerequisite and follow-up tools, giving useful contextual 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states the mutation risk, required OAuth scopes, environment-selection behavior, expected response shape, failure conditions, and safety warnings, providing comprehensive transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections, making it scannable and front-loaded with the core purpose. Each section adds operational detail, though minor redundancy exists (e.g., 'Risk' and 'Safety warnings' overlap), keeping it from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutating tool with no output schema, and the description fully covers expected response shape, failure conditions, permissions, environment selection, and an example. This is enough for an agent to select and invoke the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It adds meaningful context for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, but leaves authorizationKey and preferredAuthType undocumented, and the 'no endpoint-specific parameters' note is vague. This partial compensation is adequate but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Initialize Chat Group' as a specific verb+resource, which is clear at a basic level. However, it does not differentiate from sibling tools like x_api_create_chat_conversation or explain what 'initialize' means in contrast to 'create', leaving some ambiguity about scope and intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance with named alternatives (x_schema_discovery, x_query_suggestion) and lists recommended prerequisite/follow-up tools. The positive 'Use when' condition is tautological, but the exclusion and alternative guidance is useful for selection.
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?
With no annotations, the description fully discloses behavioral traits: it labels the operation as mutating/high-risk, specifies required OAuth scopes, explains tenant principal selection, gives expected response shape, lists failure conditions, and includes safety warnings. This is rich context beyond what annotations would 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections, front-loads the core purpose, and every sentence adds useful information (risk, permissions, failure modes, example). It is efficient for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage constraints, auth requirements, response shape, failure conditions, and an example. Since there is no output schema or annotations, it carries the full burden and does so thoroughly, though it could be more explicit about the multi-step upload flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId and credentialKey, and notes that body carries the payload. However, it does not explain authorizationKey or preferredAuthType, and with 0% schema coverage, it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Initialize media upload' with a specific verb and resource. However, it does not explicitly contrast with sibling media-upload tools like x_api_media_upload or x_api_chat_media_upload_initialize, so it misses sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Do not use when' guidance to prefer schema discovery for exploration and a more specific auth/configuration tool before API calls. It also lists recommended prerequisite/follow-up tools, but the 'Use when' section is tautological and does not compare against sibling media-upload 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?
With no annotations, the description carries the full burden and does so thoroughly: it discloses mutating/high-risk behavior, required OAuth scopes, environment-selection logic for scopeTenantId/scopeUserId/scopeAccountId, credentialKey behavior, expected response shape, common failures, and safety warnings. This far exceeds typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use when, Risk, Required permissions, etc.) and each section provides unique information. Though moderately long, it is front-loaded with the core purpose and every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers many contextual aspects: permissions, environment selection, response shape, failures, and safety. However, it does not explain the media upload workflow or how this tool relates to the step-specific upload siblings, and with no output schema and 0 required parameters flagged, an agent may not know how to construct a valid request payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains scopeTenantId, scopeUserId/scopeAccountId, credentialKey, and body in context, but leaves preferredAuthType, multipartForm, and authorizationKey under-specified. The example includes only scopeTenantId, scopeUserId, and body, not the full parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload media'—a specific verb and resource—but does not differentiate from sibling upload tools like x_api_initialize_media_upload, x_api_append_media_upload, or x_api_finalize_media_upload. It remains ambiguous whether this tool handles a complete upload or a single step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides 'Use when' and 'Do not use when' guidance, explicitly naming x_schema_discovery and x_query_suggestion for exploration, and lists prerequisite/follow-up tools. However, it does not explain when to choose this tool over step-specific media upload siblings, leaving a gap in alternative selection.
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?
No annotations are provided, so the description fully discloses behavioral traits. It clearly states 'Risk: mutating, high-risk' and 'Safety warnings: This mutates X state,' plus required OAuth scopes, environment-selection behavior, common failure conditions, and expected response shape. This is comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with useful labeled sections and front-loaded with the purpose. It is somewhat lengthy but each section adds value. Minor redundancy exists (e.g., 'Use when: Repost Post' and risk repeating safety warnings), but overall it is organized and not excessively verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, no output schema, no annotations), the description covers auth, environment selection, failure modes, expected response, and even an example. Missing details about the body payload and preferredAuthType, but the provided context is sufficient for an agent to invoke the tool with caution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey via environment-selection behavior, and id as required path. However, body is only described as 'documented request payload' with no detail, and authorizationKey/preferredAuthType are not explained. Partial coverage leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Repost Post.' which is a clear verb+resource action. It distinguishes from siblings like x_api_unrepost_post and x_api_create_posts, though it doesn't elaborate on what 'repost' entails (e.g., creates a retweet). The purpose is specific enough to guide selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Do not use when' guidance with alternatives (x_schema_discovery, x_query_suggestion) and a list of recommended prerequisite/follow-up tools. However, the 'Use when: Repost Post' is tautological and doesn't add usage context. Overall, it gives clear direction on when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does exceptionally well. It declares read-only risk, details OAuth token and scope requirements, explains environment-selection behavior, provides an expected response shape, and lists common failure conditions and safety warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it easy to parse. It contains some redundancy (e.g., 'Risk: read-only' repeated in safety warnings), but remains appropriately concise for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description covers purpose, usage, permissions, environment selection, parameter constraints, response envelope, failures, and prerequisites. The main gap is the unspecified structure of the 'data' field inside the response, leaving the search result payload unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists parameter formats and constraints, and explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId/credentialKey. However, preferredAuthType and authorizationKey remain unexplained, and test_mode semantics are unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search for Community Notes Written', identifying the verb and resource. It is distinct from sibling tools like create/delete/evaluate community notes, though it does not explicitly call out the differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Use when' and 'Do not use when' section, with explicit alternatives like x_schema_discovery or x_query_suggestion for exploration. Recommended prerequisite and follow-up tools are also listed, giving solid guidance on when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers extensively: it discloses mutating/high-risk nature, required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and explicit safety warnings. This goes far beyond the schema and provides the agent with crucial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Permissions, Environment, Parameters, Response, Failures, Recommended Tools, Safety, Example), making it scannable. It is fairly long but each section earns its place. Minor redundancy exists in the opening 'Send Chat Message' and the tautological 'Use when' line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 params, no output schema, and no annotations, the description is remarkably comprehensive: it covers response shape, failure modes, prerequisites, environment behavior, and gives an example. The only gap is incomplete parameter semantics for all fields, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains id and body, and clarifies scopeTenantId/scopeUserId/scopeAccountId/credentialKey through environment-selection behavior, plus authorizationKey in safety warnings. However, preferredAuthType is never mentioned, and 'body is used for the documented request payload' is vague. Partial coverage only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Send Chat Message', a clear verb+resource statement that immediately distinguishes this tool from sibling chat tools like x_api_send_chat_typing_indicator or x_api_create_chat_conversation. The tool's purpose is unmistakable despite the tautological 'Use when: Send Chat Message' line.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some guidance: 'Do not use when' lists exploration/configuration contexts and suggests x_schema_discovery or x_query_suggestion. It also lists recommended prerequisite/follow-up tools. However, the 'Use when' is purely tautological and does not clarify when to choose this over other messaging tools such as x_api_create_direct_messages_conversation.
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?
With no annotations, the description carries the full burden and does so thoroughly. It discloses read-only risk, bearer token requirement, environment-selection behavior for scoped credentials, expected response shape, common failure conditions, and safety warnings about sensitive data. This far exceeds typical tool descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections, making it easy to scan. It includes some redundancy, such as the tautological 'Use when: Stream all Likes' and repeated read-only statements in Risk and Safety warnings, but overall each section adds practical value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema, no annotations), the description is remarkably complete. It covers purpose, usage boundaries, auth prerequisites, environment selection, parameter constraints, response shape, failure modes, recommended companion tools, safety, and an example.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents backfill_minutes, partition, start_time, and end_time with types and required status, and explains scopeTenantId/scopeUserId/scopeAccountId/credentialKey semantics in the environment-selection section. However, authorizationKey and preferredAuthType are not mentioned, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream all Likes,' which clearly identifies a specific verb and resource, and 'all' indicates the firehose scope. However, it does not explicitly contrast with sibling tools like x_api_stream_likes_sample10 or x_api_stream_likes_compliance, so some differentiation is left to the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Use when' and 'Do not use when' sections, but 'Use when: Stream all Likes' is essentially a tautology. It does offer useful exclusions for exploratory use and points to x_schema_discovery/x_query_suggestion, but it fails to give guidance on when to choose this firehose over the sibling likes streaming 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?
With no annotations provided, the description takes on full transparency responsibility. It discloses read-only risk, bearer token requirements, environment-selection behavior for scoped credentials, common failure conditions, and safety warnings about sensitive data. This goes far beyond what annotations would typically provide and gives the agent a clear picture of side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections (Use when, Risk, Required permissions, Environment-selection, Parameter formats, Expected response, Failure conditions, Recommended tools, Safety, Example). Each section adds value, though the 'Use when' line is redundant and the overall length is substantial. It is organized enough to be navigable without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 10 parameters, no annotations, and no output schema, the description covers a remarkable amount: purpose, usage, risk, permissions, environment behavior, parameter constraints for key fields, expected response shape, failure conditions, recommended auxiliary tools, safety warnings, and an example call. This provides an agent with nearly everything needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains the meaning of scopeTenantId, scopeUserId/scopeAccountId, credentialKey, and lists four query parameters with types. However, it inaccurately constrains 'partition' and 'backfill_minutes' to integers when the schema permits string representations. It also omits authorizationKey and preferredAuthType, leaving important gaps for a 10-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream Posts compliance data,' which clearly identifies the verb (stream), resource (posts), and domain (compliance). While it does not explicitly contrast with siblings like x_api_stream_posts_firehose or x_api_stream_posts_sample, the 'compliance' qualifier in both the name and description helps differentiate it from those general streams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections. The 'Use when' is tautological, repeating the purpose, but the 'Do not use when' gives actionable guidance: avoid when auth/configuration tools are needed first, and prefer x_schema_discovery or x_query_suggestion for exploration. It also recommends prerequisite and follow-up tools, further aiding selection.
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?
With no annotations provided, the description fully carries the transparency burden. It discloses that the tool is mutating and high-risk, lists required OAuth scopes, describes auth resolution behavior via tenant/user/account scopes, notes common failure conditions (rate limits, auth failures, missing credentials), and includes a safety warning to validate scope/payload before use. This is exceptional detail for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections and front-loaded purpose. It contains useful details without excessive prose. Minor redundancy exists: 'Use when: Update List' repeats the first line, and 'Risk: mutating' overlaps with the safety warning section. Overall, the structure makes the content scannable and the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is quite comprehensive for a tool with no output schema or annotations: it covers expected response shape, common failures, permissions, auth resolution, and provides an example call. It does not mention the requirement that the authenticated user must own the list being updated, which is an important context gap. Despite that, it is far above a minimal viable description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies id is a required path parameter, body is the payload, and explains scopeTenantId/scopeUserId/scopeAccountId plus credentialKey roles. However, authorizationKey and preferredAuthType are not explained, and body semantics are only vaguely described as 'the documented request payload'. This is partial but not complete coverage of the 8 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update List', which is a clear verb+resource pairing. While it essentially restates the tool name, the subsequent parameter and response details confirm this is about updating an existing X list by ID. It distinguishes from create/delete/get list tools by the 'Update' verb, though it doesn't elaborate on exactly what updatable fields are supported.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' conditions, noting that exploration should go through x_schema_discovery or x_query_suggestion and that auth/config tools may be needed first. It also lists recommended prerequisite and follow-up tools. However, it doesn't explicitly mention alternative list operations like create/delete, relying instead on the tool naming convention.
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?
With no annotations, the description carries full burden and meets it: declares 'Risk: read-only', lists required OAuth scopes and token types, explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, gives failure conditions, and warns about sensitive data. This goes well beyond basic disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections (Use when, Risk, Permissions, etc.). Some redundancy exists: 'Use when: Validate subscription' is tautological, and read-only is mentioned twice. Still, each section serves a purpose and the example is helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides expected response shape, common failures, prerequisites, safety warnings, and recommended tools. However, the core semantics of 'validate' (what action is performed) are not explained, and with no output schema, the response shape is only partially described. Generally thorough but with a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in the 'Environment-selection behavior' section, but leaves authorizationKey and preferredAuthType unexplained. For webhook_id it only restates 'path, unknown, required'. Partial compensation, not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Validate subscription' with a clear verb and resource, and the tool name specifies 'account activity subscription'. It distinguishes from siblings like create/get/delete via the unique 'validate' verb, though it doesn't explicitly contrast with those alternatives. A score of 4 reflects clear purpose with minor ambiguity about what 'validate' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes 'Use when' (tautological) and 'Do not use when' (when auth/config tools needed or exploring), plus recommended prerequisite tools like x_schema_discovery and x_auth_get_scope_credentials. It gives some exclusions and context but doesn't explicitly compare to sibling subscription tools, so not a 5.
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?
With no annotations, the description carries full burden and does well. It discloses the mutating, high-risk nature, required OAuth scopes, environment-selection behavior for tenant principal resolution, expected response shape, common failure conditions, and explicit safety warnings. This goes far beyond a basic tool description and gives the agent a solid behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Permissions, Environment-selection, Parameters, Response, Failures, Prerequisites, Safety, Example). Each section adds unique value, and the example is useful. It is longer than typical but appropriately so for a complex tool with no annotations. No redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, no output schema, no annotations), the description covers most critical aspects: auth requirements, environment selection, failure modes, response shape, and safety. It falls short only on fully documenting all parameters (notably authorizationKey and preferredAuthType) and the body structure, but overall it provides a strong operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains participant_id as path/required and body as the request payload, and clarifies the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment selection. However, it leaves authorizationKey and preferredAuthType unexplained, and the body schema is unspecified. Partial compensation for a low-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource: 'Create DM message by participant ID.' This distinguishes it from sibling tools like x_api_create_direct_messages_by_conversation_id and x_api_create_direct_messages_conversation by specifying the unique identifier (participant ID). The purpose is immediately unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the purpose ('Create DM message by participant ID'), which is tautological. However, the 'Do not use when' guidance provides some direction, advising against using this tool when auth/config setup is needed or when exploring, preferring x_schema_discovery or x_query_suggestion first. It does not explicitly contrast with sibling DM-creation tools, so the guidance is partial but present.
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?
With no annotations, the description carries the full burden and excels: it explicitly states 'Risk: read-only', details required OAuth scopes and token types, explains environment-selection behavior with scopeTenantId/scopeUserId/scopeAccountId, provides expected response shape, lists common failure conditions, and includes a safety warning about sensitive data. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Required permissions, etc.) and front-loaded purpose. Every section adds value, and the example at the end aids understanding. Despite its length, it remains concise for the complexity it covers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 6 parameters with zero schema descriptions, the description is remarkably complete. It covers purpose, usage, auth prerequisites, environment selection, response shape, failure conditions, recommended companion tools, safety, and an example. This fully equips an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates well for several parameters. It explains that scopeTenantId plus exactly one of scopeUserId or scopeAccountId selects the tenant principal, and that credentialKey selects a non-default credential profile. However, it does not explicitly describe authorizationKey or preferredAuthType, and the statement 'no endpoint-specific parameters' offers limited format guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get personalized Trends' with a specific verb and resource, and the name itself differentiates it from the sibling tool x_api_get_trends_by_woeid. However, it does not explicitly contrast with that sibling or elaborate on what 'personalized' entails, so it stops short of fully distinguishing itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Use when' section that restates the purpose ('Get personalized Trends') and a 'Do not use when' section that advises exploration tools like x_schema_discovery. It gives some context for when to use this tool vs. exploration but does not compare it with alternative trends endpoints or specify when to prefer one over another.
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?
With no annotations, the description carries the full behavioral disclosure burden. It explicitly states read-only risk, required OAuth scopes, environment-selection behavior for tenant/principal resolution, common failure conditions, and safety warnings about sensitive data. This is comprehensive and goes well beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear labels (Use when, Risk, Required permissions, etc.). Every section adds value—covering prerequisites, environment behavior, failure modes, and an example—making the length justified and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no output schema, and no annotations, the description thoroughly covers auth prerequisites, environment selection, parameter constraints, failure conditions, and even provides a concrete JSON example. It also mentions recommended companion tools, making it highly complete for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description adds meaningful semantics by identifying id as a path parameter, max_results as an integer query parameter, and pagination_token as a query parameter. It also explains how scopeTenantId, scopeUserId, scopeAccountId, and credentialKey control auth resolution, which is not evident from the raw schema. The remaining parameters (authorizationKey, preferredAuthType) are not addressed, so it is not a perfect 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get followed Lists,' a specific verb and resource that clearly identifies the operation. However, it does not explicitly distinguish this from sibling tools like x_api_get_users_owned_lists or x_api_get_lists_followers, so it misses the top tier for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause that advises using x_schema_discovery or x_query_suggestion during exploration and avoiding this tool when auth/configuration tools are needed. It does not, however, explain when to choose this tool over alternative list-related tools, leaving usage context only partially specified.
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?
With no annotations provided, the description carries the full burden and excels: it discloses read-only risk, bearer token requirement, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This goes well beyond minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose. It is mostly efficient, but the 'Use when: Stream filtered Posts' line is redundant with the first sentence, and 'Risk: read-only' is repeated in the safety warning, keeping it from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is remarkably complete for a complex tool with no annotations or output schema: it covers purpose, auth prerequisites, scoping behavior, response shape, failure conditions, and an example. However, it omits the need to configure filtering rules (e.g., via x_api_update_rules) and leaves authorizationKey/preferredAuthType undefined, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates by explaining the scopeTenantId/scopeUserId/scopeAccountId/credentialKey selection behavior and providing formats for backfill_minutes, start_time, and end_time. However, authorizationKey and preferredAuthType are not explained, leaving a notable gap for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Stream filtered Posts,' which uses a specific verb and resource and hints at a distinct filtered-stream capability. However, it does not explicitly differentiate from sibling stream tools like x_api_stream_posts_firehose or x_api_stream_posts_sample, so the distinction is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections, and it recommends x_schema_discovery or x_query_suggestion for exploration. However, the 'Use when' clause is tautological ('Stream filtered Posts'), and the exclusion focuses on exploration/auth configuration rather than comparing with other stream tools, making the guidance useful but not fully targeted.
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?
With no annotations, the description fully carries behavioral disclosure. It specifies read-only risk, required bearer token, environment-selection behavior, expected response shape, common failures, and a safety warning about sensitive data. This goes far beyond basic read/write classification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear labeled sections (Risk, Required permissions, Parameter formats, etc.), front-loads the primary purpose, and each sentence adds unique value. Despite its length, it remains concise and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex streaming tool with 10 parameters, no output schema, and no annotations, this description is remarkably complete. It covers prerequisites, environment selection, parameter formats, response shape, failure conditions, safety, and an example, leaving little ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by detailing formats and constraints for key parameters (backfill_minutes, partition, start_time, end_time) and explaining the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it leaves authorizationKey and preferredAuthType unaddressed, which is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream all Posts,' which clearly identifies the verb (stream) and resource (all Posts). However, it does not explicitly differentiate from language-specific firehose siblings (e.g., x_api_stream_posts_firehose_en), making the scope somewhat ambiguous. The purpose is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause directing users to x_schema_discovery or x_query_suggestion for exploration, and recommends prerequisite tools. However, it does not address when to use this firehose vs. sample streams or language-specific firehose variants, leaving a gap in alternative selection.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states read-only risk, bearer token prerequisites, auth resolution behavior via scopeTenantId/scopeUserId/scopeAccountId, common failure conditions, and safety warnings. This is comprehensive and goes well beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and includes an example, making it easy to scan. It is long but mostly purposeful, though it repeats 'Stream sampled Posts' in the 'Use when' line, which is redundant and slightly wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex streaming tool with no output schema, the description covers prerequisites, expected response shape, failure conditions, recommended related tools, and safety. It is missing detailed semantics for two auth-related parameters and does not clarify how this sample stream differs from sample10/firehose alternatives, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, plus backfill_minutes as a query integer. However, authorizationKey and preferredAuthType are left unexplained, and the exact constraint of exactly one scopeUserId/scopeAccountId is only partially clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool streams sampled Posts, using a specific verb and resource. However, it does not differentiate from siblings like x_api_stream_posts_sample10 or x_api_stream_posts_firehose, and 'sampled' is generic without indicating which sample tier this is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit 'Use when' and 'Do not use when' guidance, and recommends alternatives like x_schema_discovery and x_query_suggestion for exploration. The 'Use when' statement is tautological, and it does not compare against other streaming tools, but the guidance is otherwise actionable.
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?
With no annotations, the description carries the full burden and succeeds: it discloses mutation risk ('Risk: mutating, high-risk'), safety warnings, required OAuth scopes, auth resolution behavior, and common failure conditions. This goes far beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose. Some redundancy exists (e.g., 'Use when: Unmute User' repeats the name), but overall it is information-dense and organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description is remarkably complete. It covers auth prerequisites, environment selection, expected response shape, failure modes, recommended prerequisite/follow-up tools, and provides an example, leaving few gaps beyond parameter-level details already scored.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and lists the two required path parameters. However, it omits authorizationKey and preferredAuthType, and labels parameter formats as 'unknown'. The example is also incomplete, missing the required target_user_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Unmute User' as a specific verb+resource action. This unambiguously distinguishes it from sibling tools like x_api_mute_user and x_api_get_users_muting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line is tautological ('Unmute User'), but the 'Do not use when' section provides some operational context: prefer x_schema_discovery or x_query_suggestion when exploring, and use auth/configuration tools when setup is needed. However, it does not explicitly compare to sibling tools focused on the same user relationship.
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?
With no annotations, the description discloses mutating/high-risk status, required OAuth scopes/token types, environment-selection behavior, common failure conditions, and a safety warning. This fully compensates for absent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Labeled sections make the content scannable and front-loaded, but there is mild redundancy ('Create draft Article' repeated and risk stated twice). Still, every section earns its place given the lack of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes expected response shape, failure conditions, recommended tools, and an example, which is strong for a mutating API wrapper. The main shortfall is incomplete parameter coverage for authorizationKey/preferredAuthType and body payload details, preventing a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains scopeTenantId/scopeUserId/scopeAccountId selection and credentialKey selection, which adds value beyond the bare schema. However, authorizationKey and preferredAuthType are not explained, and body is only described as 'documented request payload' without structure. With 0% schema coverage, this leaves significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening 'Create draft Article.' states a specific verb and resource, clearly distinguishing this from the sibling x_api_article_publish. Even without a title, the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections give clear invocation context and steer exploration to x_schema_discovery/x_query_suggestion. It could more directly contrast with x_api_article_publish, but the draft/publish naming separation plus alternatives is adequate.
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?
With no annotations, the description carries the full transparency burden. It explicitly states risk ('mutating, high-risk'), required permissions, common failure conditions, safety warnings, and environment-selection behavior. This thoroughly discloses the tool's behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use when, Risk, Required permissions, etc.), making it scannable. It is somewhat verbose, and 'Use when: Create subscription' is redundant, but each section essentially contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema, no annotations), the description is highly complete. It covers expected response shape, common failure conditions, prerequisites, safety warnings, and provides an example. This is a well-rounded tool description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining webhook_id, body, and the scope parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey). However, authorizationKey and preferredAuthType are not explicitly explained, though authorizationKey is mentioned in the safety warning. Significant meaning is added but not for all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Create subscription,' which is a clear verb+resource statement. The tool name adds specificity about 'account activity,' but the description itself does not distinguish it from the sibling x_api_create_activity_subscription. It is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Do not use when' section with alternatives (x_schema_discovery, x_query_suggestion) and prerequisites, such as required OAuth scopes. However, the 'Use when' section is tautological ('Create subscription') and does not specify scenarios or differentiate from closely related 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?
Despite having no annotations, the description discloses key behavioral traits: it is 'mutating, high-risk', requires specific OAuth scopes, explains environment-selection behavior for auth resolution, gives the expected response shape, lists common failure conditions, and includes safety warnings. This fully compensates for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, but it repeats 'Create Chat Group Conversation' in the 'Use when' line and somewhat overlaps between 'Risk' and 'Safety warnings'. Overall, it is efficient for the complexity of a mutating tool with auth prerequisites, though a bit redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, risk, auth, environment behavior, failures, and response shape, which is substantial. However, the critical 'body' parameter is left undefined, and the expected response shape is generic. For a create operation, the absence of body structure guidance is a significant gap that limits the tool's invokability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It partially explains scopeTenantId, scopeUserId/scopeAccountId, and credentialKey via environment-selection behavior, but it does not clarify the 'body' parameter's structure beyond calling it 'the documented request payload', nor does it explain authorizationKey or preferredAuthType. This is insufficient for 7 undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create Chat Group Conversation', which is a specific verb+resource statement. It clearly distinguishes this tool from siblings like x_api_get_chat_conversations and x_api_create_direct_messages_conversation by naming the exact action and resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, naming alternatives like x_schema_discovery and x_query_suggestion. Also lists recommended prerequisite and follow-up tools, giving clear guidance on sequencing and when to avoid the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden and succeeds. It explicitly labels the operation as 'Risk: mutating, high-risk,' states required bearer token, explains environment-selection behavior, provides expected response shape, common failure conditions, and a safety warning to validate scope and authorizationKey. This goes beyond basic disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose. It is verbose but each section adds value. Minor redundancy: 'Deletes X activity subscription' appears in both the opening and 'Use when' section, wasting a sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex X API delete operation with 7 parameters and no output schema, the description provides a thorough profile: purpose, exclusions, risk, permissions, environment selection, param constraints, response shape, failure modes, prerequisite/follow-up tools, safety warning, and example. It is effectively complete, though not all optional params are individually explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must compensate. It explains the environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and lists subscription_id as path/required. However, authorizationKey and preferredAuthType are not described, and 'unknown' for format is unhelpful. The example demonstrates a valid invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Deletes X activity subscription.' However, it is essentially tautological with the tool name and does not distinguish from sibling tools like x_api_delete_activity_subscriptions_by_ids or x_api_delete_account_activity_subscription. The 'Use when' line repeats the same sentence, adding no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Do not use when' section that advises against using when auth/config tools are needed or when exploring, and recommends alternative tools (x_schema_discovery, x_query_suggestion). It also lists prerequisite and follow-up tools. However, it does not explicitly compare with deletion siblings (e.g., batch vs single), so the guidance is context-rich but not fully alternative-aware.
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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states the tool is mutating and high-risk, lists required OAuth scopes, explains environment-selection behavior, gives an expected response shape, and lists common failure conditions. This is comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Risk, Required permissions, Parameter formats, Expected response, etc.). It is lengthy but informative, with only clear redundancy being 'Use when: Delete List' repeated after the initial 'Delete List.' Overall, the structure helps scanning, though it could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no annotations, no output schema), the description is remarkably complete: it covers auth prerequisites, selection of credentials, failure modes, response shape, safety warnings, and an example. The main gap is the lack of detailed semantics for all parameters, particularly authorizationKey and preferredAuthType, which prevents full self-contained operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for several parameters: it explains that scopeTenantId plus scopeUserId or scopeAccountId selects the auth tenant principal, and credentialKey selects a non-default credential profile. It also mentions id as required path parameter. However, with 0% schema coverage, two parameters (authorizationKey, preferredAuthType) are not explained, and the description says id's format is 'unknown' rather than providing useful details like 'the ID of the list to delete.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Delete List,' which is a specific verb+resource that clearly states the tool's function. This distinguishes it from siblings like x_api_create_lists, x_api_get_lists_by_id, and x_api_update_lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' section that explicitly tells the agent to prefer x_schema_discovery or x_query_suggestion for exploration, and to use auth/configuration tools when needed. It also lists recommended prerequisite and follow-up tools. However, the 'Use when' clause merely restates the tool's purpose ('Delete List') and lacks specific conditions or context for when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states 'Risk: mutating, high-risk', 'This mutates X state', required OAuth scopes/tokens, common failure conditions, and environment-selection behavior. This is rich, actionable behavioral disclosure beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections, making it scannable. Some redundancy exists (e.g., 'Risk: mutating, high-risk' and 'Safety warnings: This mutates X state'), but the overall density is high and the example adds practical value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes expected response shape, common failure conditions, prerequisites, and follow-up tools, which is substantial given there is no output schema. However, it lacks specifics about the request payload for evaluating a community note, a meaningful gap for a 7-parameter tool with no required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the roles of scopeTenantId, scopeUserId/scopeAccountId, credentialKey, and body, but it omits authorizationKey and preferredAuthType entirely. The body is only described as 'used for the documented request payload', leaving the actual payload structure undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Evaluate a Community Note' using a specific verb and resource, which clearly identifies the tool's action. It is distinguishable from sibling tools like x_api_create_community_notes and x_api_delete_community_notes, though it could be more explicit about what 'evaluate' entails (e.g., submitting a rating).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including alternatives like x_schema_discovery and x_query_suggestion. It also recommends prerequisite and follow-up tools, giving the agent clear direction on when to invoke this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It clearly warns 'Risk: mutating, high-risk' and 'Safety warnings: This mutates X state,' along with required OAuth scopes, environment-selection behavior, common failure conditions, and expected response shape. This exceeds what annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Risk, Permissions, Environment-selection, Parameter formats, Response, Failure conditions, Prerequisites, Safety, Example), making it highly readable. The 'Use when: Finalize Media upload' line is redundant, but the rest is information-dense without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of output schema, the description provides expected response shape, failure conditions, prerequisites, and safety warnings. It lacks explicit sequencing with sibling upload tools (e.g., 'call after append_media_upload'), which would improve completeness for an agent navigating the upload workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does for many parameters: explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in the environment-selection behavior, and references authorizationKey in safety warnings. However, it does not explain preferredAuthType or provide structured detail for all 7 parameters, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Finalize Media upload,' a specific verb+resource phrase that clearly identifies the tool's purpose. It distinguishes from sibling upload tools (initialize, append, get status) by using 'finalize,' which denotes the completion step of a multipart upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a 'Use when' clause that simply restates the tool name ('Finalize Media upload') and a 'Do not use when' clause that is generic to exploration/auth setup, naming x_schema_discovery and x_query_suggestion. It lacks explicit guidance on how this tool fits into the upload workflow relative to siblings like x_api_initialize_media_upload or x_api_append_media_upload, so the when-to-use guidance is only implied.
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?
With no annotations, the description fully bears the transparency burden. It discloses read-only risk, required OAuth scopes, environment-selection behavior, parameter formats, expected response shape, common failure conditions, and safety warnings about sensitive data. This is exceptional detail for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and an example, making it easy to scan. It is longer than typical, but most content is operational and not filler. The only redundancy is 'Use when: Get Chat Conversations,' which adds no value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no annotations, and no output schema, the description is remarkably complete. It covers permissions, auth behavior, response shape, failure conditions, and even a detailed example. The minor omissions (two parameter meanings) are outweighed by the rich operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains six of eight parameters: scopeTenantId, scopeUserId, scopeAccountId, credentialKey, max_results, and pagination_token. It misses authorizationKey and preferredAuthType, and describes max_results as integer while the schema also allows numeric strings. Given 0% schema coverage, this partial but meaningful explanation warrants a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get Chat Conversations,' which clearly identifies the verb and resource. The plural form distinguishes it from the singular sibling tool x_api_get_chat_conversation, but it does not explicitly say 'list' or 'retrieve all conversations for the authenticated user.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Do not use when' section gives explicit exclusions (exploration, need for auth/configuration) and directs to x_schema_discovery/x_query_suggestion. It also lists recommended prerequisite/follow-up tools, giving useful context. However, 'Use when' is tautological, and there is no direct comparison with singular chat conversation 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?
With no annotations provided, the description carries full behavioral disclosure. It states 'Risk: read-only', details required permissions (bearer, OAuth 2 scopes, OAuth 1a), explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, lists common failure conditions, and provides safety warnings about sensitive data. This goes well beyond minimal requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections: Use when, Do not use when, Risk, Permissions, Environment-selection, Parameter formats, Expected response, Failure conditions, Recommended tools, Safety, and Example. It is dense and informative without redundant filler, though it could be trimmed slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 7 parameters, no annotations, and no output schema, the description is remarkably complete. It covers expected response shape, failure conditions, permissions, environment selection, safety, and gives a concrete example. It also points to prerequisite and follow-up tools, providing the agent with sufficient context 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does explain key parameters: id (path, required), scopeTenantId/scopeUserId/scopeAccountId selection logic, and credentialKey. It does not describe authorizationKey or preferredAuthType, but the example and auth sections provide context. Overall, it adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Post by ID', a clear verb+resource statement that conveys the tool's primary function. However, it does not explicitly differentiate from the closely named sibling x_api_get_posts_by_ids (plural), relying on the name itself for distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Do not use when' clause that excludes exploration and points to x_schema_discovery or x_query_suggestion as alternatives. It also lists recommended prerequisite tools. The 'Use when' clause is tautological ('Get Post by ID'), so it lacks a rich positive usage scenario, but the exclusion and alternatives are helpful.
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?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It comprehensively covers read-only nature, required permissions and scopes, environment/tenant selection, expected response shape, common failure conditions, and safety warnings about sensitive data. This exceeds the typical level of transparency and fully compensates for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, making it easy to scan. Most sections earn their place. The 'Use when' line is redundant with the opening sentence, and the 'Recommended prerequisite and follow-up tools' could be considered extraneous, but the structure remains effective and mostly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and no output schema, this description provides substantial context: permissions, auth resolution, response shape, failure modes, and an example. It lacks explicit guidance on choosing between scopeUserId and scopeAccountId, and omits authorizationKey/preferredAuthType, but overall it is thorough enough for an agent to use the tool correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains user_ids (query, array, required) and details the scope parameters (scopeTenantId, scopeUserId/scopeAccountId, credentialKey) in the environment-selection behavior. However, authorizationKey and preferredAuthType are not described, leaving a partial gap. Overall, it adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Spaces by creator IDs' with a specific verb and resource, and the qualifier 'by creator IDs' distinguishes it from sibling tools like x_api_get_spaces_by_ids, x_api_get_spaces_by_id, and x_api_search_spaces. This is unambiguous 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the purpose ('Get Spaces by creator IDs'), offering no additional guidance. The 'Do not use when' clause provides generic advice about auth/configuration and exploration tools, but it does not compare this tool to alternatives like x_api_get_spaces_by_ids or x_api_search_spaces. Usage context is implied but not explicitly differentiated from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: states read-only risk, required permissions (bearer token, OAuth scopes), environment-selection behavior, expected response shape, common failures, and safety warnings about sensitive data. This far exceeds minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it scannable. However, it contains redundancy ('Get Users by IDs' appears in the title and again in 'Use when'), and the length could be trimmed slightly without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description provides the expected response shape, failure conditions, and recommended follow-up tools. It covers auth and environment selection comprehensively, but the missing parameter semantics for two parameters prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the meaning of ids, scopeTenantId, scopeUserId/scopeAccountId, and credentialKey, but omits authorizationKey and preferredAuthType. The parameter guidance is partial, leaving two parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Users by IDs' with a specific verb and resource. It distinguishes from sibling tools like x_api_get_users_by_id (singular) and x_api_get_users_by_username (by username) through the plural 'IDs'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' guidance, advising against use when exploration is needed and pointing to x_schema_discovery and x_query_suggestion. It also lists recommended prerequisite tools. However, it could more clearly contrast with similar user-fetching 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?
With no annotations provided, the description carries full burden and does so thoroughly. It discloses read-only nature, required OAuth scopes and token types, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive account data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings and a useful example. It is longer than minimal but each section adds value. Minor redundancy exists in repeating 'Get my User' in the Use when section, but overall the structure is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 'get my user' tool with no output schema and zero annotation coverage, the description is quite complete. It covers purpose, usage, behavior, params (partially), failures, prerequisites, and example. The main gap is incomplete parameter semantics for all 6 params, but overall it is comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the key scoping parameters (scopeTenantId, scopeUserId, scopeAccountId, credentialKey) and states there are no endpoint-specific parameters. However, it does not explain authorizationKey or preferredAuthType, leaving some params undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with 'Get my User', which is a specific verb+resource ('get' + current user). It distinguishes from sibling tools like x_api_get_users_by_id by the 'my' qualifier, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, naming specific alternative tools (x_schema_discovery, x_query_suggestion) and conditions for not using this tool. This is excellent guidance for an agent selecting among many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden and succeeds by disclosing read-only risk, required OAuth tokens and scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This is far beyond a minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose. It is slightly verbose and includes a tautological 'Use when: Search Communities' line, but most sections earn their place given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description provides substantial context: auth prerequisites, environment selection, response wrapper, failure modes, and an example. However, it omits two parameters and gives only a generic response shape rather than community-specific fields, leaving some gaps for a 10-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 10 parameters and 0% description coverage, so the description must compensate. It covers query, max_results, next_token, pagination_token, and environment-selection parameters, but it leaves authorizationKey and preferredAuthType undocumented. It also labels next_token and pagination_token as 'unknown,' which adds little semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search Communities,' a specific verb+resource statement that clearly identifies the action. It is distinguishable from siblings like x_api_get_communities_by_id, but it does not elaborate on what data is returned or how search results are scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use when: Search Communities' and 'Do not use when... prefer x_schema_discovery or x_query_suggestion first.' It also lists recommended prerequisite and follow-up tools, giving clear direction 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?
With no annotations provided, the description takes on the full burden of disclosure. It states 'Risk: read-only,' required bearer token, environment-selection behavior, common failure conditions, and safety warnings. This is substantial, though it does not delve into streaming connection lifecycle or pagination behavior, which would be useful for a firehose tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections (Use when, Risk, Required permissions, etc.), making it scannable. It contains minor redundancy ('Use when: Stream Japanese Posts' repeats the purpose), but every other section adds valuable information without excessive wordiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, no output schema, and no annotations, the description covers a broad range: purpose, usage, auth prerequisites, environment behavior, parameter constraints, response shape, failure conditions, and safety. It falls short on fully explaining all parameters (e.g., authorizationKey, preferredAuthType) and the exact semantics of streaming, but overall it is nearly complete for a complex API wrapper.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameter formats for backfill_minutes, partition, start_time, and end_time, but these mostly repeat the schema types. It adds meaningful context for scopeTenantId/scopeUserId/scopeAccountId auth resolution, but omits authorizationKey and preferredAuthType semantics. With schema coverage at 0%, the description should compensate further for the remaining six parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream Japanese Posts,' which clearly identifies the action (stream) and the resource (Japanese posts). This is specific and distinguishes it from sibling firehose tools for other languages (en, ko, pt) and from generic search/stream endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when' and 'Do not use when,' recommending x_schema_discovery or x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools, providing clear guidance on when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does exceptionally well. It discloses the mutating, high-risk nature, required bearer token, environment-selection behavior for scope/credential resolution, common failure conditions (e.g., missing credentials, rate limits), and safety warnings about validating scope and payload before use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections that make it scannable and information-dense. It is longer than strictly necessary—for instance, the 'Use when' line repeats the opening phrase—but each section like 'Common failure conditions' and 'Expected response shape' serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex wrapper tool with no output schema and no annotations, the description is quite complete: it covers response shape, failure conditions, prerequisites, safety, and an example. However, it doesn't explain what a compliance job is in domain terms or what the body payload should contain, relying on 'documented request payload' as a placeholder.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the semantics of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey, plus the role of body. However, it leaves authorizationKey and preferredAuthType unaddressed beyond the safety warning mentioning authorizationKey, so not all parameters gain additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a compliance job with the verb+resource phrase 'Create Compliance Job.' However, it does not elaborate on what a compliance job is or explicitly distinguish itself from sibling tools like x_api_get_compliance_jobs or x_api_get_compliance_jobs_by_id, though the verb 'create' does differentiate it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including alternatives like x_schema_discovery and x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools, which gives an agent clear decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool is mutating and high-risk, lists required OAuth scopes, explains environment-selection behavior, details common failure conditions, and includes safety warnings. This goes far beyond a basic description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but extremely well-structured with labeled sections (Use when, Risk, Required permissions, etc.). The core purpose is front-loaded, and each section provides distinct, useful information. The only minor redundancy is 'Use when: Create DM conversation,' which restates the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with no output schema, the description covers expected response shape, failure conditions, prerequisites, an example, and related tools. This gives an agent everything needed to understand when and how to invoke the tool and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It effectively explains the scopeTenantId/scopeUserId/scopeAccountId relationship, the role of credentialKey, and that body holds the request payload. However, it omits explicit semantics for authorizationKey and preferredAuthType, though these are fairly self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create DM conversation,' which clearly identifies the action and resource. However, it does not distinguish this tool from sibling DM creation tools like x_api_create_direct_messages_by_participant_id or x_api_create_direct_messages_by_conversation_id; the tool's unique name is the main differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides 'Use when' and 'Do not use when' sections, explicitly steering exploration toward x_schema_discovery or x_query_suggestion. It also lists recommended prerequisite and follow-up tools. However, the 'Use when' line is tautological and it does not explicitly compare against specific sibling DM creation 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?
With no annotations, the description fully carries the transparency burden. It discloses mutating/high-risk behavior, bearer-token requirement, environment-selection semantics, common failure conditions, expected response shape, and safety warnings. This goes well beyond minimal expectations and helps the agent anticipate side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, making it scannable. However, it is verbose and contains redundancy: 'Create stream link' appears both as the opening and again under 'Use when'. Some details, like 'unknown' in the parameter format, add little value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, no annotations, and no output schema, the description is remarkably complete. It includes required permissions, environment selection, parameter constraints, expected response structure, failure conditions, safety warnings, recommended tools, and an example. This is sufficient for an agent to invoke the tool with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains path vs query placement for webhook_id and tweet/expansion fields, defines the scopeTenantId/scopeUserId/scopeAccountId selection behavior, and clarifies credentialKey's role. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action 'Create stream link', which clearly identifies the tool's operation and aligns with the tool name. It distinguishes from the sibling get/delete stream-link tools by verb, though it does not elaborate on what a 'stream link' represents in the webhook context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, and recommends alternative tools like x_schema_discovery and x_query_suggestion for exploration. It also lists prerequisite and follow-up tools, giving practical guidance, although the 'Use when' clause largely restates the purpose.
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?
With no annotations, the description carries full behavioral burden and does so well. It discloses that the operation is mutating and high-risk, explains environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, describes expected response shape, common failure conditions, and includes explicit safety warnings about validating scope and payload before use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clearly labeled sections and front-loads the core purpose. The 'Use when: Terminate multiple connections' line is redundant, and the overall length is substantial, but every section adds useful operational detail. It is well-structured and not padded with fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is quite thorough for a complex mutation tool: it covers risk, prerequisites, environment-selection, response shape, failure modes, safety, and the example. The main gap is that it never specifies what the 'documented request payload' in body should contain, which is important for actually deleting connections by UUIDs. Still, it provides far more contextual detail than the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds valuable semantics by explaining that scopeTenantId plus exactly one of scopeUserId/scopeAccountId selects the auth principal, credentialKey selects a non-default credential profile, and body carries the request payload. However, it does not describe preferredAuthType or the exact structure of the body payload, which limits completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Terminate multiple connections,' which is a clear verb+resource pairing. However, it does not explicitly mention 'by UUIDs' or contrast with sibling deletion tools like x_api_delete_all_connections and x_api_delete_connections_by_endpoint, so it does not fully distinguish itself within the description itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use when: Terminate multiple connections' and a 'Do not use when' section that directs agents away from exploratory use and toward x_schema_discovery or x_query_suggestion. It also lists recommended prerequisite and follow-up tools and required permissions, making when-to-use conditions very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It transparently states the tool is read-only, lists required permissions/scopes, explains environment-selection behavior for tenant/account identity, and documents common failure conditions and safety warnings, going far beyond minimal expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but meticulously structured with labeled sections (Use when, Risk, Required permissions, etc.). Every sentence provides distinct value—no filler—and the example at the end is practical. The structure makes it easy to scan and reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema or annotations, the description covers expected response shape, common failure conditions, prerequisites, safety warnings, and even an invocation example. For a tool with 9 parameters, this is remarkably complete and leaves little ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 9 parameters with 0% coverage, but the description adds meaning by specifying parameter formats and constraints for id, max_results, and pagination_token, and explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. It does not describe all parameters, but the critical ones are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get List members' which is a clear verb+resource pair, and the tool name further reinforces its function. However, it does not explicitly differentiate from sibling tools like x_api_get_lists_followers beyond the word 'members' versus 'followers', so it stops short of full distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance and names alternative tools (x_schema_discovery, x_query_suggestion) for exploration, plus recommended prerequisite and follow-up tools. However, the 'Use when' section simply repeats 'Get List members' without adding contextual use cases or exclusions beyond the when-not section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly. It discloses read-only risk, required bearer token, auth resolution behavior, common failure conditions, and a safety warning about sensitive account data. This goes well beyond minimal disclosure and does not contradict any structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections for risk, permissions, environment behavior, parameter formats, response shape, failures, and recommended tools. The 'Use when: Get stream rules' line repeats the opening and adds no value, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 9 parameters, no annotations, and no output schema, the description is remarkably complete. It includes expected response shape, common failure conditions, auth prerequisites, safety warnings, and an example invocation. This is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists ids, max_results, and pagination_token with basic formats, and adds meaningful context for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey via environment-selection behavior. However, authorizationKey and preferredAuthType are not explained at all, leaving gaps for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get stream rules,' which names a specific verb and resource and distinguishes it from closely related siblings like x_api_get_rule_counts. However, it does not elaborate on the scope or nature of the rules beyond the tool name, and the 'Use when: Get stream rules' line is purely tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use when: Get stream rules' and a clear exclusion clause: 'Do not use when: a more specific auth/configuration tool is required... prefer x_schema_discovery or x_query_suggestion first.' It also names recommended prerequisite and follow-up tools, satisfying the when/when-not/alternatives criterion.
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?
No annotations are provided, so the description carries full responsibility. It discloses read-only risk, sensitive data warnings, required permissions (bearer token and OAuth 2 scopes), environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear section labels and flows logically. It is longer than the 1-2 sentence ideal, but the length is justified by the tool's complexity and lack of annotations. Some redundancy exists ("Use when: Get space by ID" repeats the purpose), but overall it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no annotations, no output schema), the description is remarkably complete. It covers purpose, usage, permissions, response shape, failure conditions, prerequisites, follow-up tools, safety, and an example. The expected response shape compensates for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description explains some parameters (scopeTenantId, scopeUserId/scopeAccountId, credentialKey) through environment-selection behavior. However, it does not explain authorizationKey or preferredAuthType, and only id is listed in the parameter formats section. The description adds meaning but is incomplete for all seven parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with "Get space by ID," a specific verb and resource that clearly states the tool's function. It differentiates from sibling tools by the singular ID focus (e.g., x_api_get_spaces_by_ids) and includes a usage directive. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit "Use when" and "Do not use when" sections, including alternatives like preferring x_schema_discovery or x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools. The "Use when" phrasing is tautological but the additional guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does exceptionally well. It discloses read-only risk, required OAuth scopes (space.read, tweet.read, users.read), environment-selection behavior for scoped credentials, expected response shape, common failure conditions, and safety warnings about sensitive data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into labeled sections and front-loads the purpose. Each section adds value, but the 'Use when: Get Spaces by IDs' line is a redundant tautology that should have been omitted. Overall, it remains efficient for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and annotations, the description is remarkably complete. It covers auth prerequisites, environment-selection behavior, parameter roles, expected response shape, failure conditions, and recommended companion tools, leaving little room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining ids as 'query, array, required', specifying that scopeTenantId plus exactly one of scopeUserId/scopeAccountId selects the auth principal, and describing credentialKey as selecting a non-default profile. It misses authorizationKey and preferredAuthType, but overall provides substantial parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Spaces by IDs,' a specific verb+resource+scope statement. It clearly distinguishes from sibling tools like x_api_get_spaces_by_id (singular) and x_api_get_spaces_by_creator_ids by emphasizing plural IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line merely restates the tool's name/function ('Get Spaces by IDs'), providing no decision context. The 'Do not use when' section offers some guidance, steering users toward exploratory tools like x_schema_discovery or x_query_suggestion, but it does not explicitly compare to related space-fetching siblings, leaving ambiguity about which get_spaces variant to choose.
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?
With no annotations, the description carries the full burden for behavioral disclosure. It transparently covers risk (read-only), required permissions, environment-selection behavior, expected response shape, common failures, and safety warnings, far exceeding basic disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections for usage, risk, permissions, parameters, response, failures, and example. Each section is concise and adds value; the format is scannable and front-loaded with a one-line summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no output schema, no annotations), the description covers purpose, usage, permissions, environment scoping, response shape, failures, and safety. It omits details on authorizationKey and preferredAuthType, and the concept of 'affiliates' is not expanded, but the example helps. Still, most key aspects are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, so the description must explain parameters. It explicitly documents id, max_results, and pagination_token formats, and explains scopeTenantId, scopeUserId, scopeAccountId, and credentialKey via behavior text. However, authorizationKey and preferredAuthType are not described, leaving gaps for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get affiliates.' which clearly indicates the action and resource. It is specific enough to distinguish from siblings since no other tool targets affiliates, though it lacks a brief elaboration of what affiliates are in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' instructions, naming alternatives like x_schema_discovery and x_query_suggestion for exploration. This gives clear decision guidance for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to lean on, the description carries the full burden and delivers: it discloses the mutating/high-risk nature, required OAuth scopes, environment-selection behavior, common failure conditions, and a safety warning to validate scope/payload/authorizationKey. This is commendably comprehensive and goes well beyond what annotations typically convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections and is front-loaded with the clear purpose. It is long but appropriate for the tool's complexity and auth requirements. The only redundancy is 'Use when: Add List member,' which adds no information, but the overall structure makes it scannable and each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description impressively provides expected response shape, failure conditions, permissions, and environment selection. It could dive deeper into the body payload structure, but it compensates by recommending x_schema_discovery for such details, making the tool usable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds some meaning via 'Parameter formats and constraints' (id, body) and environment-selection behavior (scopeTenantId, scopeUserId, scopeAccountId, credentialKey). However, it omits explanations for authorizationKey and preferredAuthType, and the body description is vague ('used for the documented request payload'), so it only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add List member,' a specific verb+resource statement that clearly distinguishes this mutation tool from siblings like x_api_get_lists_members and x_api_remove_lists_member_by_user_id. The 'Use when' repeats the name, but the core statement is unambiguous and lacks the tautology that plagues weaker definitions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Do not use when: a more specific auth/configuration tool is required before the API call or you are only exploring; prefer x_schema_discovery or x_query_suggestion first,' and lists recommended prerequisite/follow-up tools like x_connection_info and x_auth_upsert_principal_credentials. This gives clear, actionable guidance on when to use the tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the transparency burden. It discloses high-risk mutation, required permissions and auth scopes, environment-selection behavior, common failure conditions, and a safety warning. This is rich behavioral context beyond what structured fields provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded with the core purpose. The 'Use when' line is somewhat redundant with the first sentence, but every other section contributes meaningful information without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, lack of output schema, and 7 undocumented parameters, the description is remarkably complete. It provides expected response shape, failure conditions, required permissions, environment-selection details, and a concrete example, covering the major operational aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the relationship between scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and clarifies that body holds the request payload. However, authorizationKey and preferredAuthType are only minimally addressed, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create X activity subscription,' a clear verb+resource combination. However, it does not differentiate this from sibling tools like x_api_create_account_activity_subscription, so it is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('Create X activity subscription') and provides a 'Do not use when' section naming alternatives such as x_schema_discovery and x_query_suggestion. It also lists recommended prerequisite and follow-up tools, giving strong usage 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?
No annotations are provided, so the description is the sole source for behavioral disclosure. It thoroughly covers mutating risk, required permissions (bearer token, OAuth 1a user token), environment-selection behavior (scopeTenantId plus exactly one of scopeUserId/scopeAccountId), expected response shape, and common failure conditions, exceeding typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-structured with labeled sections. It's front-loaded with 'Create webhook.' Some redundancy exists (e.g., 'Use when: Create webhook' repeats the first line), but every other sentence provides valuable context. The format aids scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description provides extensive context: response shape, auth prerequisites, failure conditions, safety warnings, and an example invocation. This is sufficient for an agent to correctly invoke the tool in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% description coverage, so the description must compensate. It explains the roles of scopeTenantId, scopeUserId, scopeAccountId, credentialKey, and body, including the requirement of exactly one user/account scope. However, authorizationKey and preferredAuthType are not explained beyond a validation mention, so compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create webhook,' which clearly identifies the action and resource. However, it doesn't distinguish among sibling tools like x_api_create_webhook_replay_job or x_api_create_webhooks_stream_link, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' conditions, and suggests x_schema_discovery and x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools, giving clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses the mutating high-risk nature, required bearer/OAuth tokens, environment-selection behavior, expected response shape, common failure conditions, and safety warnings about validating scope/payload/authorizationKey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loads the core purpose. The 'Use when: Delete webhook' line is redundant with the opening sentence, which adds slight clutter, but the overall organization is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema and annotations, the description covers purpose, permissions, environment behavior, parameter basics, expected response, failure conditions, recommended tools, and an example. This provides enough context for the agent to invoke the tool correctly in most situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains webhook_id, scopeTenantId/scopeUserId/scopeAccountId selection for auth resolution, and credentialKey behavior. However, it does not clarify authorizationKey or preferredAuthType, leaving some parameter semantics to inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the clear verb+resource statement 'Delete webhook.' It is unambiguous about the core action, but it does not explicitly differentiate from sibling tools like x_api_delete_webhooks_stream_link or x_api_validate_webhooks. The purpose is clear without being deeply scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including alternatives: 'prefer x_schema_discovery or x_query_suggestion first' for exploration. It also lists recommended prerequisite and follow-up tools, giving the agent clear direction on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses read-only risk, required bearer/OAuth token scopes, tenant/credential selection behavior, failure modes, and a warning about sensitive data in responses. This is far beyond minimal and provides rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose, and most content is useful. The 'Use when: Get Community by ID' line is redundant with the opening, and the parameter section is thin, but overall it is organized and not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and no output schema, this description covers prerequisites, expected response shape, failure conditions, environment selection, and an example. It still lacks direct guidance for authorizationKey/preferredAuthType and doesn't explicitly mention the search alternative, but it is substantially complete for invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains environment-selection semantics for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and identifies id as path/required with an example. However, authorizationKey and preferredAuthType are not explicitly described, leaving two parameters under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Community by ID,' a specific verb+resource statement that clearly identifies the tool's function. It distinguishes from sibling search tools by emphasizing retrieval by unique ID, and the scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections, naming x_schema_discovery and x_query_suggestion as alternatives for exploration, and warns against using before auth/configuration. However, it doesn't directly contrast with the sibling x_api_search_communities, so the guidance is strong but not fully differentiated.
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?
With no annotations provided, the description carries the full burden and does so well. It states 'Risk: read-only', required bearer token, environment-selection behavior for scopes and credentials, expected response shape, common failure conditions, and safety warnings about sensitive data. This goes well beyond the minimal 'read-only' and provides actionable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labeled sections. Each sentence adds value: risk, permissions, environment behavior, parameter constraints, response shape, failures, recommended tools, safety, and an example. It is appropriately sized for the tool's complexity and not padded with fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no annotations, and no output schema, the description is remarkably comprehensive. It covers the operation, constraints, auth/auth resolution, response shape, failure modes, prerequisites, and provides a concrete example. The inclusion of follow-up tools and safety warnings makes it a complete guide for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains woeid and max_trends with path/query and type constraints, and elaborates on scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in the environment-selection section. However, authorizationKey and preferredAuthType are not explained, leaving a gap for those parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Get Trends by WOEID', a specific verb and resource that clearly identifies the operation. It distinguishes from the sibling x_api_get_trends_personalized_trends by the WOEID scope, and the rest of the description reinforces this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' line merely repeats the description without adding context. The 'Do not use when' section gives useful exclusions (auth/config tools, exploration) and names x_schema_discovery and x_query_suggestion as alternatives, but it does not explicitly direct users to the competing trends tool (x_api_get_trends_personalized_trends) as an alternative for personalized trends.
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?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It clearly states 'Risk: mutating, high-risk' and 'Safety warnings: This mutates X state. Validate scope, payload, and authorizationKey before use.' It also details required permissions (OAuth scopes), environment-selection behavior, common failure conditions (auth failures, rate limits), and the expected response shape, providing comprehensive transparency beyond the bare mutation hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Required permissions, etc.) and includes an example, making it easy to parse. It is somewhat verbose but each section adds value, with only minor redundancy between 'Risk: mutating' and 'Safety warnings: This mutates X state.' Overall, it is appropriately sized and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no annotations, no output schema), the description is remarkably complete. It covers the purpose, usage conditions, permissions, environment selection, parameter formats, expected response shape, common failures, recommended companion tools, safety warnings, and an example. This is sufficient for an agent to decide when and how to invoke the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains tweet_id as 'path, unknown, required' and notes that body is 'used for the documented request payload.' It also describes the environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and mentions authorizationKey in safety warnings. However, preferredAuthType is not explicitly explained, and some parameters like authorizationKey are not given a full semantic description, but the provided information is substantial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Hide reply.' which clearly identifies the action on a resource, and the surrounding context (e.g., expected response shape, example) reinforces this purpose. However, it is terse and does not elaborate on the scope (e.g., hiding a reply on a specific post) or distinguish from any potential sibling tools beyond the name. It is clear but not maximally 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when: Hide reply.' and 'Do not use when: a more specific auth/configuration tool is required before the API call or you are only exploring; prefer x_schema_discovery or x_query_suggestion first.' It also lists 'Recommended prerequisite and follow-up tools' including x_connection_info and x_auth_upsert_principal_credentials, giving clear guidance on when and when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It explicitly states 'Risk: mutating, high-risk,' required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This is comprehensive transparency beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it scannable. It avoids fluff but is somewhat repetitive (e.g., 'Like Post' appears in the opening and in 'Use when'). Overall, the density of useful information justifies a score above average, though it could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutating, high-risk tool with 8 parameters and no output schema, yet the description covers required permissions, environment behavior, parameter roles, response shape, failure conditions, and even provides an example invocation. It leaves little uncovered for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description adds meaningful semantics for key parameters: 'id (path, unknown, required)' and 'body is used for the documented request payload.' It also explains how scopeTenantId, scopeUserId, scopeAccountId, and credentialKey work together for auth resolution. However, it does not explain authorizationKey or preferredAuthType in detail, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Like Post,' which clearly identifies the action and resource, but it does little more than restate the tool name and does not explicitly distinguish this from sibling tools like x_api_unlike_post or x_api_get_posts_liking_users. The overall purpose is unambiguous, but the differentiation relies on the tool name rather than the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' guidance, including concrete alternatives: 'prefer x_schema_discovery or x_query_suggestion first' when exploring. This satisfies the requirement for clear usage context and exclusions, earning a top score.
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?
With no annotations provided, the description fully carries the burden. It explicitly labels the tool 'mutating, high-risk', warns to 'Validate scope, payload, and authorizationKey before use', details required OAuth scopes, explains environment-selection behavior, lists common failure conditions, and provides an expected response shape. This is exemplary disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, front-loaded with the core action. It avoids excessive fluff, but there is redundancy: 'Add members to a Chat group conversation' appears both as the opening and again in 'Use when'. The structure is clear and each section adds value, so it earns a strong score despite minor repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutating tool with 8 parameters, no output schema, and no annotations, the description is remarkably complete. It covers permissions, risk, environment-selection, parameter roles, response shape, failure conditions, recommended companion tools, and an example. This gives an agent sufficient information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains key parameters: 'id (path, unknown, required)', 'body is used for the documented request payload', and the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution. It also gives a concrete example with argument names. However, it does not elaborate on the structure of 'body', which would be the payload for adding members.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Add members to a Chat group conversation' with a specific verb and resource, clearly distinguishing it from sibling chat tools like create_chat_conversation or send_chat_message. The action is unambiguous and scoped to chat group membership.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' section merely restates the purpose, but the 'Do not use when' provides valuable exclusions: avoid when a more specific auth/configuration tool is needed or when exploring, preferring x_schema_discovery or x_query_suggestion. This gives context for when not to invoke, though it doesn't compare this tool to other mutation tools for chat groups specifically.
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?
With no annotations provided, the description fully discloses the operation's read-only nature, required OAuth scopes and tokens, environment-selection behavior, common failure conditions, and a safety warning about sensitive data. This exceeds the typical level of behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and provides dense information. The only redundancy is repeating 'Download Chat Media' in 'Use when', but overall it is concise given the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no annotations, and no output schema, the description is remarkably complete. It covers purpose, usage restrictions, permissions, parameter behaviors, response shape, failure modes, example, and related tools—everything an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains the meaning of key parameters: environment-selection for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. It identifies id and media_hash_key as required path parameters. However, it omits explanations for authorizationKey and preferredAuthType, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Download Chat Media', a specific verb and resource that clearly states the tool's function. It distinguishes from upload and other chat tools by indicating a download operation, and the example and response shape reinforce the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' guidance, recommending x_schema_discovery or x_query_suggestion for exploration. It also lists prerequisite and follow-up tools. However, the 'Use when' line is a tautology and it does not differentiate from the similar sibling x_api_dm_conversations_media_download.
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?
No annotations are provided, so the description carries the full burden. It clearly states the mutating/high-risk nature, required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This is comprehensive and goes beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Required permissions, etc.), and nearly every sentence provides value. However, the 'Use when' section redundantly repeats the purpose, and the overall length is somewhat verbose, though acceptable given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 params, no output schema, no annotations), the description is remarkably complete. It includes purpose, usage exclusions, permissions, environment-selection behavior, parameter constraints, expected response shape, failure conditions, recommended tools, safety warnings, and an example. This 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining key parameters: dm_conversation_id (path/string/required), body usage, and the scopeTenantId/scopeUserId/scopeAccountId/credentialKey semantics for auth resolution. It does not explicitly describe preferredAuthType, but the enum in the schema partially covers that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create DM message by conversation ID', providing a specific verb and resource. It distinguishes from sibling tools like x_api_create_direct_messages_conversation and x_api_create_direct_messages_by_participant_id by specifying 'by conversation ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance (e.g., if auth/config tools needed or exploring, prefer x_schema_discovery or x_query_suggestion) and lists recommended prerequisite/follow-up tools. However, the 'Use when' section merely repeats the purpose and does not compare with the sibling tool for creating by participant ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully shoulders the burden by disclosing mutating/high-risk status, required OAuth permissions, common failure conditions, and a safety warning. It even explains environment-selection behavior for auth resolution. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than typical but uses clear label-framed sections, making information scannable. Every section adds necessary context—permissions, risk, response shape, failure modes—with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7-parameter schema with no descriptions and no output schema, the description provides expected response shape, failure conditions, prerequisites, and an example. It covers the critical operational aspects needed to invoke the tool safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the description compensates by explaining scopeTenantId, scopeUserId/scopeAccountId selection, credentialKey behavior, and body usage. However, authorizationKey and preferredAuthType are not explicitly explained, so it is not fully complete but is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create or Edit Post,' clearly identifying the tool's function and resource. It is distinct enough from siblings like x_api_delete_posts, though it does not explicitly differentiate from other post-related create/edit operations. The verb-resource pairing is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' conditions, including directing users away when only exploring and toward x_schema_discovery or x_query_suggestion. It also lists recommended prerequisite and follow-up tools, giving clear context for when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully carries the burden: it explicitly flags the operation as mutating and high-risk, requires bearer token, details environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This is exemplary transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose, but contains redundancy (e.g., 'Use when' repeats the first sentence; risk is mentioned twice). It is dense and useful, though not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and 7 parameters with 0% schema coverage, the description provides a surprising amount of context: response shape, failure conditions, prerequisites, safety, environment behavior, and an example. This makes the tool actionable despite the opaque body parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the scope parameter relationship (scopeTenantId plus exactly one of scopeUserId/scopeAccountId), credentialKey's role, and body usage. It does not explicitly explain preferredAuthType or authorizationKey details, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create replay job for webhook,' which is a specific verb+resource statement that clearly distinguishes this tool from siblings like x_api_create_webhooks and x_api_create_webhooks_stream_link. The resource 'replay job' is unique and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Do not use when' section provides explicit exclusions and names alternative tools (x_schema_discovery, x_query_suggestion) for exploration or auth/configuration tasks. However, the 'Use when' line simply repeats the purpose rather than giving a substantive usage condition, which prevents a perfect score.
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?
With no annotations provided, the description carries full burden and excels. It discloses risk ('mutating, high-risk'), required permissions ('bearer token'), environment-selection behavior (scopeTenantId plus scopeUserId/scopeAccountId, credentialKey), common failure conditions, and safety warnings. This goes far beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections (Use when, Risk, Required permissions, etc.), making it easy to scan. It is slightly verbose with some repetition (the purpose line reappears in 'Use when'), but every section contributes distinct operational detail. This is efficient for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 7 parameters, no annotations, and no output schema, the description covers all key aspects: purpose, usage boundaries, risk, permissions, environment behavior, param formats, expected response shape, failure conditions, recommended tools, safety warnings, and an example. This is comprehensive for a mutating API tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add parameter meaning. It explains ids as 'query, array, required' and clarifies the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment selection. However, it does not elaborate on authorizationKey or preferredAuthType, leaving some parameters to rely on schema constraints alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete X activity subscriptions by IDs', which clearly states the action (delete), the resource (X activity subscriptions), and the scope (by IDs, distinguishing it from singular deletion tools like x_api_delete_activity_subscription). This is a specific verb+resource+differentiator.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections. The 'Do not use when' section mentions preferring x_schema_discovery or x_query_suggestion for exploration and notes when auth/configuration tools are needed. However, the 'Use when' section simply restates the purpose, and it does not explicitly contrast with sibling deletion tools (e.g., singular vs. plural). This is clear context with some alternatives, but not exhaustive.
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?
No annotations are provided, so the description carries the full burden. It thoroughly discloses mutating/high-risk nature, required OAuth scopes, environment-selection behavior for tenant/auth resolution, common failure conditions, and safety warnings. This goes well beyond basic operation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and a concrete example, with the purpose front-loaded. Minor redundancy: 'Delete DM event' appears both at the opening and in 'Use when', which could be trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is remarkably complete. It covers purpose, usage exclusions, permissions, environment selection, parameter formats, expected response shape, failure conditions, recommended tools, safety warnings, and an example—everything needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining event_id as a required path parameter, and clarifying the role of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey in auth resolution. It does not fully define authorizationKey or preferredAuthType, but the safety warning references authorizationKey, providing partial context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete DM event'—a specific verb and resource. It clearly distinguishes from sibling DM tools (e.g., get/create) via the delete verb and the targeted resource, avoiding tautology or ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Do not use when' exclusions (exploring, needing auth/config tools) and lists recommended prerequisite and follow-up tools. However, 'Use when: Delete DM event' is tautological, and it does not directly contrast with alternative DM event tools (e.g., get vs. delete).
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?
With no annotations, the description fully discloses the mutating high-risk nature, required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This provides comprehensive behavioral context beyond the bare operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and is information-dense, but contains some redundancy such as 'Use when: Delete Bookmark' and repeating the mutating risk in both the Risk and Safety Warnings. It is somewhat lengthy but each section contributes useful details for a no-annotation scenario.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with 8 parameters, no output schema, and no annotations, the description covers prerequisites, environment selection, parameter constraints, response shape, failure conditions, and recommended tools. It also provides an example, making it highly complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 0%, the description explains the required parameters (id, tweet_id) and the scoping behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it omits semantics for preferredAuthType and authorizationKey, which are only mentioned in a safety warning without explaining their use. Thus it adds value but does not fully compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete Bookmark' with a specific verb and resource, distinguishing it from sibling tools like x_api_create_users_bookmark and x_api_get_users_bookmarks. The purpose is unambiguous and directly matches the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Do not use when' guidance, mentioning alternative tools like x_schema_discovery and x_query_suggestion, and lists recommended prerequisite/follow-up tools. However, the 'Use when' section merely restates 'Delete Bookmark' and adds no additional context, so it is not fully explicit on when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It explicitly notes read-only risk, required OAuth scopes and token types, environment-selection behavior for auth resolution, common failure conditions (e.g., missing credentials, rate limits), and safety warnings about sensitive data. This substantially exceeds baseline expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, each providing essential information without redundancy. Every sentence adds value, from permissions to failure conditions to an example. It is appropriately sized for the tool's complexity and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description specifies the expected response shape. It covers prerequisites, environment behavior, failure conditions, recommended companion tools, and safety warnings. This makes the tool self-contained and actionable for an agent, with no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by detailing four required parameters with their API names, locations, types, and required status (ids, end_time, start_time, granularity). It also explains the behavior of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it does not cover all 10 parameters (e.g., authorizationKey, preferredAuthType), so not fully complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get Post analytics' as the core purpose, which is a specific verb and resource. It doesn't explicitly differentiate from other analytics tools like x_api_get_media_analytics or x_api_get_insights_historical, but the name and description make the target clear. The 'Use when' section is somewhat tautological but the overall context resolves ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, including specific alternatives like x_schema_discovery or x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools, offering clear direction on when to invoke this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it declares read-only risk, required OAuth scopes, tenant/auth resolution behavior, response shape, common failure conditions, and a safety warning about sensitive data. This goes far beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Risk, Permissions, etc.), making it scannable. It is lengthy but each section adds valuable context. The only waste is the tautological 'Use when: Get Space ticket buyers.' line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no output schema, the description provides comprehensive context: response shape, failure conditions, prerequisites, environment selection, and an example. This is sufficient for an agent to invoke the tool correctly without additional resources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 0%, the description compensates by explaining id, pagination_token, max_results formats, and the behavior of scopeTenantId, scopeUserId/scopeAccountId, and credentialKey. It does not cover authorizationKey or preferredAuthType, but the schema provides an enum for the latter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource phrase: 'Get Space ticket buyers.' This unambiguously distinguishes it from sibling tools like x_api_get_spaces_by_id, x_api_get_spaces_posts, or x_api_search_spaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a 'Do not use when' clause that names alternatives (x_schema_discovery, x_query_suggestion) and suggests prerequisite tools. However, the 'Use when' section merely restates the tool's purpose ('Get Space ticket buyers'), offering no deeper guidance on when to choose this specific tool over similar Space-focused API 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?
With no annotations, the description fully discloses risk (mutating, high-risk), required OAuth scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. It provides comprehensive behavioral context well beyond minimal requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections, making it easy to scan. Some redundancy exists ('Mark Conversation as Read' appears both as title and in 'Use when'), but each section adds meaningful detail, and length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description provides expected response shape, examples, prerequisites, failure modes, and recommended companion tools. It covers all necessary context for an agent to safely and correctly invoke this mutation, including environment-selection details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explaining id (path, required), body (request payload), and the scope/credential selection semantics for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it leaves authorizationKey and preferredAuthType under-explained, though the schema enum provides some guidance for the latter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Mark Conversation as Read' with a specific verb and resource. It distinguishes from sibling tools like x_api_get_chat_conversation or x_api_send_chat_message by targeting a distinct mutation. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, mentioning alternatives like x_schema_discovery and x_query_suggestion for exploration, and auth/configuration tools before API calls. However, it does not explicitly contrast with other chat conversation tools, leaving some ambiguity for selecting this action over similar mutations.
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?
With no annotations provided, the description fully carries the behavioral transparency burden. It discloses read-only risk, required bearer token, environment-selection logic for scopeTenantId/scopeUserId/scopeAccountId, credentialKey behavior, expected response shape, common failure conditions, and safety warnings about sensitive data. This is comprehensive and goes well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections covering usage, risk, permissions, environment behavior, parameters, response, failures, and example. It is somewhat long but appropriately so for a complex tool. The 'Use when' section redundantly repeats the first sentence, which is minor waste, but overall every other sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 10-parameter schema, no annotations, and no output schema, the description is exceptionally complete. It covers prerequisites, environment-selection behavior, response shape, common failure conditions, recommended tools, safety warnings, and an example. This gives an agent sufficient context to decide when and how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains parameter formats and constraints for backfill_minutes, partition, start_time, and end_time, and clarifies the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution. However, it does not explicitly mention authorizationKey or preferredAuthType, leaving those two parameters unexplained despite a schema coverage of 0%. Still, it compensates well for most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Stream 10% sampled Posts.' This is a specific verb (stream) plus resource (Posts) with a sampling rate (10%) that distinguishes it from sibling stream tools like firehose or compliance. The purpose is immediately clear and matches the tool name without being a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, naming alternatives like x_schema_discovery and x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools. However, it does not explicitly compare against other Post stream tools (e.g., firehose vs sample10) beyond the name itself, which slightly limits differentiation.
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?
With no annotations, the description fully discloses the tool's mutating and high-risk nature, required OAuth scopes, environment-selection behavior, common failure conditions, and safety warnings. This is comprehensive behavioral context beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with labeled sections and front-loaded purpose. Minor redundancy exists between the 'Risk' line and 'Safety warnings,' but the overall format is scannable and justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers permissions, environment selection, expected response shape, failure conditions, and includes an example, making it largely complete for invocation. It lacks detailed body content specifications, but points to the 'documented request payload' as the source.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining that body carries the API payload and detailing how scopeTenantId, scopeUserId/scopeAccountId, and credentialKey affect auth resolution. However, authorizationKey and preferredAuthType are not explained, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create Media metadata,' clearly identifying the action and resource. It distinguishes from sibling tools like x_api_create_media_subtitles and x_api_media_upload by specifying 'metadata.' Despite echoing the tool name, it is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' sections, including a clear directive to prefer x_schema_discovery or x_query_suggestion when exploring. This gives the agent concrete guidance on when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it states the mutating/high-risk nature, required bearer token, environment-selection behavior for scope parameters, safety warnings, expected response shape, and common failure conditions. This is far beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but extremely well-structured with labeled sections: Use when, Do not use when, Risk, Prerequisites, Environment-selection behavior, Parameter formats, Expected response shape, Failure conditions, Recommended tools, Safety warnings, and Example. Every section adds value, and the example at the end is practical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, high-risk tool with no output schema and no annotations, the description covers all necessary aspects: operation, usage boundaries, permissions, environment scope, response shape, failure modes, recommended companion tools, and an example. It is effectively complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the meaning of scopeTenantId, the XOR relationship of scopeUserId/scopeAccountId, and credentialKey. It mentions authorizationKey in safety warnings, but does not fully clarify preferredAuthType. Given empty schema, this partial compensation is good but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Terminate all connections', a specific verb+resource statement. The word 'all' distinguishes this from sibling deletion tools like x_api_delete_connections_by_uuids or x_api_delete_connections_by_endpoint, making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'Use when' (though tautological) and a 'Do not use when' that explicitly points to x_schema_discovery or x_query_suggestion for exploration and to more specific auth/configuration tools when needed. It also lists recommended prerequisite and follow-up tools, but does not explicitly compare with other connection-deletion siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It explicitly discloses that the tool is 'mutating, high-risk', lists required OAuth scopes and token types, describes environment-selection behavior, common failure conditions, and includes a safety warning. This is exceptional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with labeled sections (Use when, Risk, Required permissions, etc.) that each add value. It leads with the core action and keeps every sentence informative, including an example, without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), this description is remarkably complete. It covers purpose, usage, permissions, parameter behavior, expected response shape, failure conditions, prerequisites, safety, and an example, making it self-sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates by naming id and user_id as required path parameters and detailing environment-selection behavior for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it does not explain authorizationKey or preferredAuthType, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Remove List member', a specific verb and resource, which clearly states the tool's action. The name and description together distinguish it from siblings like x_api_add_lists_member and x_api_get_lists_members, and the example confirms the intended operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'Use when' (remove list member) though somewhat tautological, and a helpful 'Do not use when' that directs users to schema discovery or query suggestion for exploration. It also lists recommended prerequisite tools, giving clear context and exclusions, but lacks a more detailed use-case distinction.
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?
With no annotations, the description fully carries the burden. It explicitly labels the tool as 'mutating, high-risk', lists required OAuth scopes, explains environment-selection behavior (scopeTenantId with scopeUserId/scopeAccountId), enumerates common failure conditions, and gives a safety warning. This goes far beyond typical disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections. It front-loads the purpose and usage. The 'Use when' line is tautological ('Finalize Chat Media Upload'), and some content is repeated (e.g., mutating risk appears in both Risk and Safety warnings), but overall each section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 8 parameters, no output schema, and no annotations, the description is exceptionally complete. It includes expected response shape, failure conditions, prerequisites, recommended follow-up tools, and a concrete example, leaving little ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the key parameters: id (path, string, required), body as request payload, and the scoping behavior for scopeTenantId/scopeUserId/scopeAccountId, plus credentialKey. However, authorizationKey and preferredAuthType are not described, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Finalize Chat Media Upload', a specific verb and resource that clearly identifies the action. It is distinguished from siblings like initialize, append, and download by the word 'finalize', and the overall context makes its role in the upload flow evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear guidance, including a directive to prefer x_schema_discovery or x_query_suggestion for exploration, and to use auth/configuration tools when needed. This is exactly the kind of alternative and exclusion advice expected.
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 mutation risk ('mutating, high-risk'), required OAuth scopes, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, and common failure conditions. Since no annotations are provided, this carries the full behavioral burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections. It front-loads the purpose and uses bullet-like labels, but has minor redundancy (e.g., 'Create Media subtitles' repeated in 'Use when' and 'Risk' vs 'Safety warnings'). It earns its length given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers expected response shape, failure conditions, required permissions, example invocation, and auth environment. This gives an agent enough to invoke the tool correctly and handle errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains key parameters: scopeTenantId plus exactly one of scopeUserId/scopeAccountId for tenant selection, credentialKey for profile selection, and body as the payload. However, authorizationKey and preferredAuthType are not fully elaborated, leaving a slight gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create Media subtitles,' a specific verb + resource phrase. It clearly differentiates from siblings like x_api_delete_media_subtitles (delete) and x_api_create_media_metadata (metadata vs subtitles). This leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide direct usage boundaries. The description names alternatives (x_schema_discovery, x_query_suggestion) for exploration and recommends prerequisite tools, giving an agent clear decision rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it labels the tool as 'mutating, high-risk', states required OAuth scopes, describes environment-selection behavior, and warns that it mutates X state. This satisfies the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections, each adding unique value. It is slightly verbose but not wasteful; the structure aids scanning and comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the absence of an output schema, the description comprehensively covers permissions, environment selection, parameter formats, expected response shape, common failures, and safety warnings. It leaves little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey, and clarifies that body holds the request payload. It does not explain authorizationKey or preferredAuthType, but the main parameters are addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete Media subtitles.' with a specific verb and resource, distinguishing it from sibling tools like x_api_create_media_subtitles. It immediately identifies the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, including alternatives like x_schema_discovery and x_query_suggestion for exploration. This gives clear guidance on when to invoke this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It mentions the mutating risk, safety warnings, required OAuth scopes, environment-selection behavior, and common failure conditions—comprehensive transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with labeled sections, and it is front-loaded with the core purpose. Each section provides operational value, but the overall size is near the upper limit of what is needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutating nature and lack of an output schema, the description is exceptionally complete: it includes expected response shape, common failure conditions, required permissions, environment-selection behavior, a usage example, and safety warnings. No critical aspect is left undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the required id parameter as a path parameter and detailing how scopeTenantId, scopeUserId, scopeAccountId, and credentialKey interact. However, it omits explanation for authorizationKey and preferredAuthType, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete Post.' which clearly states the verb and resource. It is unambiguously about deleting a post and distinguishes this tool from sibling tools like create, get, or search post 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide actionable guidance, including when to prefer x_schema_discovery or x_query_suggestion. It also lists recommended prerequisite and follow-up tools, making the decision to use this tool vs alternatives clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses read-only risk, required bearer token, environment-selection behavior, common failure conditions, and a safety warning about sensitive account data. This goes well beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections, but contains redundancy: 'Use when' repeats the purpose and read-only risk is stated twice. Still appropriately sized for a complex API tool with auth context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, exclusions, prerequisites, environment selection, failure conditions, response shape, safety, and an example. Despite a generic response shape and two undocumented params, the description is thorough enough for an agent to select and invoke this read endpoint correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution, adding value over the bare schema. However, it omits authorizationKey and preferredAuthType, and the 'id (path, unknown, required)' note is vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get Compliance Job by ID' with a specific verb and resource. It clearly distinguishes from sibling tools like x_api_get_compliance_jobs (list) and x_api_create_compliance_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' sections, directing exploration to x_schema_discovery or x_query_suggestion. Also lists recommended prerequisite tools, giving clear context on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so well: it states read-only risk, required OAuth/bearer permissions, environment-selection behavior for tenant principal resolution, and common failure conditions. It also warns that read-only responses can contain sensitive account data, adding meaningful safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections and front-loaded with the core purpose. It is longer than average but each section contributes; minor redundancy exists in repeating 'Get List by ID' and read-only risk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description defines the expected response shape and covers permissions, failure modes, and an example invocation. This is a high level of contextual completeness for a wrapper around a single GET endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains id as a required path parameter and clarifies the roles of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment/auth selection. However, authorizationKey and preferredAuthType are not explained, leaving some parameters to rely on their names/enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence 'Get List by ID' uses a specific verb and resource, and the name further disambiguates from sibling list-related endpoints (followers, members, posts). It clearly identifies this as a single-resource GET.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a 'Use when' condition, a 'Do not use when' exclusion for exploration scenarios, and names alternatives (x_schema_discovery, x_query_suggestion). It also lists recommended prerequisite and follow-up tools, giving an agent clear decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It thoroughly covers read-only risk, required OAuth/bearer permissions, environment-selection behavior for tenant scopes, common failure conditions, and a safety warning about sensitive data in responses. This is exceptional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections, making it scannable. However, 'Use when: Get news stories by ID' is a verbatim repeat of the opening sentence, wasting one line. Otherwise, every section adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description provides the expected response shape, common failure conditions, required permissions, environment behavior, and related tools. For a 7-parameter tool with no annotations, this is remarkably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description compensates by explaining id (path, required) and detailing scopeTenantId/scopeUserId/scopeAccountId selection behavior plus credentialKey profile selection. However, authorizationKey and preferredAuthType receive no explanation, and id's 'unknown' type is unhelpful. Most critical parameters are covered, but gaps remain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get news stories by ID', clearly identifying the action (get) and resource (news stories by ID). This distinguishes it from sibling tools like x_api_search_news and other get-by-id variants for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear guidance, including alternatives like x_schema_discovery and x_query_suggestion for exploration. It also lists recommended prerequisite and follow-up tools, giving strong contextual direction.
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?
No annotations are present, so the description carries full responsibility. It discloses risk (read-only), required permissions and scopes, environment-selection behavior for tenants and credentials, common failure conditions (including rate limits and auth failures), and safety warnings about sensitive data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections and front-loaded purpose, but it is somewhat verbose. The 'Use when' repeats the first sentence ('Get public keys for multiple users'), and the included example adds length without significant additional insight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description provides comprehensive context: expected response shape, common failure conditions, required permissions, environment selection, and recommended tools. This is sufficient for an agent to invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'ids (query, array, required)' and details the semantics of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, authorizationKey and preferredAuthType are left undocumented, despite the schema containing an enum for preferredAuthType.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get public keys for multiple users,' which clearly states the action and resource scope. It is distinguished from sibling tools like x_api_get_users_public_key (singular) and x_api_add_user_public_key, and the name aligns with the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear usage context, noting that exploration should prefer x_schema_discovery or x_query_suggestion and that specific auth/config tools may be needed first. Recommended prerequisite and follow-up tools are also listed.
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?
With no annotations present, the description fully carries the behavioral transparency burden. It discloses read-only risk, required OAuth scopes/tokens, environment-selection behavior for scopeTenantId/scopeUserId/scopeAccountId, expected response shape, common failure conditions, and safety warnings about sensitive data. This is far beyond what structured fields provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with clear labeled sections that quickly convey purpose, behavior, and constraints. It is somewhat verbose and contains a redundant 'Use when' that repeats the first line, but every other section earns its place by providing non-obvious details like failure modes and environment selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema and no annotations, the description is remarkably complete. It includes purpose, exclusions, prerequisites, environment behavior, parameter formats, response shape, failure conditions, safety warnings, and a concrete example. This gives an agent sufficient context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It does so through a 'Parameter formats and constraints' section covering test_mode, pagination_token, max_results, and post_selection, plus environment-selection semantics for scopeTenantId, scopeUserId, scopeAccountId, and credentialKey. However, it omits authorizationKey and preferredAuthType, leaving two parameters without added context, so it is not fully complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search for Posts Eligible for Community Notes', a specific verb+resource statement that clearly distinguishes this tool from general post search siblings like x_api_search_posts_all and from x_api_search_community_notes_written. The name and first line align, and the scope ('Eligible for Community Notes') makes its unique 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when' and 'Do not use when' sections provide explicit guidance, including a clear exclusion: 'prefer x_schema_discovery or x_query_suggestion first' when exploring. It also lists recommended prerequisite and follow-up tools (x_connection_info, x_auth_get_scope_credentials, x_api_request), giving the agent actionable selection criteria.
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?
With no annotations provided, the description fully discloses the mutating and high-risk nature, required OAuth tokens and scopes, environment-selection behavior, expected response shape, common failure conditions, and safety warnings. This goes far beyond a simple 'delete' statement and gives the agent a complete behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly structured with labeled sections (Use when, Risk, Required permissions, Environment-selection, Parameter formats, Expected response, Common failures, Recommended tools, Safety, Example). Every sentence adds unique value, and the content is front-loaded with the core purpose. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 7 parameters, no annotations, and no output schema, but the description covers the purpose, prerequisites, parameter behavior, expected response, failure conditions, and an example. This fully equips the agent to select and invoke the tool correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in auth resolution, and mentions id as required. It doesn't fully detail authorizationKey or preferredAuthType, but the example and safety warning reference them. Given the number of params, this is solid but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb-resource pair 'Delete a Community Note.' This clearly distinguishes it from sibling tools like create_community_notes or search_community_notes_written. The purpose is unambiguous and directly tied to the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' sections, naming alternatives like x_schema_discovery and x_query_suggestion for exploration scenarios. It also lists recommended prerequisite/follow-up tools, giving clear contextual guidance on when to invoke this tool versus exploring or configuring first.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It covers risk, required permissions, environment-selection behavior, parameter formats, expected response shape, and common failure conditions. This is comprehensive and goes well beyond what the schema alone provides, especially for a generic HTTP tool where side effects and auth behavior are critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use when, Risk, Prerequisites, Environment-selection, Parameter formats, Expected response, Failure conditions, Example). Each line adds value, and the format makes information easy to scan. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 params, no output schema, no annotations), the description is remarkably complete. It covers when to use, how to use, what parameters mean, expected response structure, failure modes, and even includes an example. This is a fully self-contained description for a generic fallback tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the required fields (method, path), JSON object types for query/headers/body, the multipart exception, scope resolution semantics, and preferredAuthType. While authorizationKey and credentialKey are not explicitly described, the coverage of the core parameters is thorough and actionable, leaving only minor gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a 'Generic X API request fallback' with the specific use case of knowing the exact path/method or testing a route. It explicitly distinguishes itself from dedicated x_api_* tools by positioning itself as a fallback, and the 'Do not use when' clause reinforces the differentiation. The verb 'request' and resource 'X API' make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' guidance, naming x_schema_discovery and dedicated tools as safer alternatives. It also gives context on risk, prerequisites, and environment selection, making it clear when this fallback is appropriate versus when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the tool is read-only, requires a bearer token, explains the scopeTenantId/scopeUserId/scopeAccountId environment-selection behavior, lists common failure conditions (missing credentials, rate limits, etc.), and warns that responses can include sensitive data. This is extensive and goes well beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear labels (Use when, Do not use when, Risk, Required permissions, Environment-selection behavior, Parameter formats, Expected response shape, Common failure conditions, Recommended tools, Safety warnings, Example). Every sentence adds distinct value, and the most critical information is front-loaded. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters and no output schema, the description provides an expected response shape, common failure conditions, recommended prerequisite/follow-up tools, a concrete example, and safety warnings. It also covers authentication and scoping semantics. This is comprehensive and gives an agent all the context needed to invoke the tool correctly, even without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds formats and constraints for backfill_minutes, partition, start_time, and end_time, and explains the role of scopeTenantId, scopeUserId, scopeAccountId, and credentialKey in environment selection. However, it omits preferredAuthType and authorizationKey, and does not explain the functional meaning of parameters like partition or backfill_minutes beyond type/requiredness. It adds significant semantics but not complete coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stream sampled Likes,' which is a specific verb and resource. The tool name includes 'sample10' and the description uses 'sampled,' distinguishing it from sibling tools like x_api_stream_likes_firehose and x_api_stream_likes_compliance. This clearly indicates what the tool does and differentiates it from similar stream 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when: Stream sampled Likes' and 'Do not use when: a more specific auth/configuration tool is required... prefer x_schema_discovery or x_query_suggestion first.' It also lists prerequisites (bearer token) and recommended follow-up tools (x_connection_info, x_auth_get_scope_credentials, x_api_request), giving clear guidance on when to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It discloses mutating/high-risk nature, bearer token requirement, scoped auth resolution behavior, expected response shape, and common failure conditions, going far beyond a minimal mention.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, the description is well-structured with labeled sections (Risk, Permissions, Environment-selection, Expected response, Failure conditions, Example), each providing unique and actionable information. The purpose is front-loaded, and no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no annotations, no output schema), the description supplies essential context: response shape, failure modes, prerequisites, environment-selection behavior, and an example. This is a complete and highly usable description for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining subscription_id as a required path parameter, body as the request payload, and the scopeTenantId/scopeUserId/scopeAccountId selection logic. However, authorizationKey and preferredAuthType are not explained, leaving a minor gap in parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'Update X activity subscription' uses a specific verb and resource, clearly distinguishing this tool from sibling create/delete/get activity subscription tools. The purpose is immediately unambiguous, and the absence of a title does not detract from clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when' conditions and 'Do not use when' exclusions, even naming alternative tools like x_schema_discovery and x_query_suggestion. This provides clear decision guidance beyond the schema and annotations.
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?
No annotations are provided, so the description carries the full burden. It discloses risk ('mutating, high-risk'), prerequisites, environment-selection behavior (Vault secrets and Postgres metadata), expected response shape, common failure conditions, and a safety warning about rotating credentials affecting all principals. This far exceeds expected transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses labeled sections ('Use when', 'Risk', 'Expected response shape', etc.) that front-load the most important information and keep each line purposeful. It is dense but well-organized, and every sentence contributes actionable guidance without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, no annotations, no output schema), the description is remarkably complete: it covers purpose, usage boundaries, risk, prerequisites, behavior, response format, failure modes, safety warnings, and a concrete example. This is a textbook example of a contextually complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates for key parameters: tenantId is explicitly required, bearerToken and OAuth1 consumer key/secret are explained as an either/or choice, and profileKey, makeDefault, and authorizationKey appear in the example with meaningful context. However, label and notes are not semantically described, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Store or rotate tenant-scoped X app credentials.' It clearly distinguishes this tool from the sibling x_auth_upsert_principal_credentials by specifying tenant-scoped app credentials vs. user/account-specific tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' and 'Do not use when:' sections provide direct guidance, including naming the alternative tool (x_auth_upsert_principal_credentials) for the excluded case. This is exactly the kind of when-to-use vs. when-not-to-use clarity desired.
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?
With no annotations provided, the description fully carries the transparency burden. It discloses the mutating, high-risk nature; the side effects on Vault and Postgres; the expected response shape; common failure conditions; and a safety warning about changing default principal profiles. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use, Risk, Required, Environment, Expected response, Common failures, Safety, Example). Every sentence adds meaningful information, and the content is front-loaded with the core purpose. It is appropriately detailed for a complex tool without wasteful prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, no annotations, no output schema), the description is remarkably complete. It covers intended use, exclusions, prerequisites, side effects, response shape, failure modes, safety implications, and an example. This provides an agent with nearly all contextual information needed to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 0% of parameter descriptions, so the description must compensate. It explains the relationship between tenantId, userId/accountId, and the OAuth1/OAuth2 token pairs, and provides a concrete example. However, some schema parameters like label, notes, xUserId, username, and profileKey remain unexplained, so it is not fully comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Store or rotate tenant/user or tenant/account X user credentials,' which precisely names the verb, resource, and scope. It clearly distinguishes this from the sibling x_auth_upsert_app_credentials by explicitly contrasting principal credentials with app-level credentials.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' conditions, and even names the alternative tool for the excluded case. It also lists required permissions/prerequisites (tenantId plus exactly one of userId or accountId) and the required token types, giving unambiguous guidance for when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/LesterAJohn/X-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server