agentView

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

Annotations indicate readOnly=false and destructiveHint=true. The description adds context about the license pool and the need for available licenses, which is beyond what annotations provide. No contradiction.

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

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

Three sentences, each serving a distinct purpose: action, resource context, and requirements. No unnecessary words.

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

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

The description covers the core functionality and requirements. An output schema exists but is not shown; however, the description is sufficient for an agent to understand the tool's purpose and prerequisites.

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

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

Schema coverage is 100%, and the tool description does not add information about the parameters beyond what's in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('distributes'), the resource ('premium display licenses'), and the target ('organization'). It distinguishes from sibling tools like assign_license by specifying allocation from the account's pool to an org.

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

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

The description mentions prerequisites: 'Requires admin scope and available premium licenses.' It does not explicitly state when not to use it, but the sibling list provides context for alternatives.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true. The description adds useful context beyond annotations: the license adds +30 MB storage. It does not cover all edge cases (e.g., what happens if no license), but provides adequate transparency.

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

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

The description is three sentences, no redundancy, front-loaded with the core action. Every sentence adds value.

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

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

Given the tool's simplicity and presence of an output schema, the description covers key behaviors: action, prerequisite, effect. It does not mention error cases or return values, but output schema handles returns. Slightly incomplete but sufficient.

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

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

Schema description coverage is 100% with both parameters documented. The description adds little beyond the schema—only the admin scope requirement is new. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Marks a display as premium using one of the account's available licenses, which removes the free-tier watermark.' It distinguishes from sibling tools like unassign_license and allocate_licenses.

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

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

The description provides clear context: use when you want to mark a display as premium and have an available license. It mentions prerequisites (unassigned license, admin scope) but does not explicitly state when not to use or compare to alternatives.

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

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

Annotations provide idempotentHint=true and destructiveHint=false; description adds that it caches identity on the session, which is a useful behavioral detail. However, it doesn't document error behavior or whether repeated calls overwrite the cached identity.

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

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

Three sentences, each serving a distinct purpose: purpose, usage guidance, and return values. No redundancy or filler. Front-loaded with core functionality.

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

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

Covers usage constraints and return values adequately. Since an output schema exists, return field descriptions are not needed here. Minor gap: no mention of error handling for invalid tokens.

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

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

Schema description coverage is 100%, with each parameter already well-documented (aliases, usage warnings). The description does not add new parameter-level detail beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the tool validates a JWT token and caches identity, distinguishing it from sibling tools like get_auth_session. The verb 'validates' and resource 'JWT agent token' are specific and unambiguous.

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

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

Explicitly advises when to use (if client can't reliably send Authorization header) and when not to (if already auto-authenticated by get_auth_session), with clear alternatives mentioned.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds that locked displays are skipped and returns lists of sent/skipped displays, and requires 'content_only' scope. However, it does not detail error handling or what happens if content fails.

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

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

The description is three sentences long, front-loaded with the primary purpose, and each sentence adds essential information without redundancy.

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

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

Given the presence of an output schema (so return format is covered elsewhere), the description adequately explains the main behavior, targeting options, scope requirement, and return lists. The optional auth parameters are standard and not critical for the core functionality.

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

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

With 100% schema description coverage, the baseline is 3. The description adds context on the usage of 'display_ids' vs 'all' but does not explain parameters like 'access_token' or 'session_request_id' beyond the schema.

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

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

The description clearly states the tool broadcasts HTML content to multiple displays, differentiating from siblings like send_html (single display) and broadcast_to_categories (by category). The verb 'broadcast' and resource 'multiple displays' are specific and distinct.

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

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

The description explicitly says to use 'display_ids' for specific targets or 'all' for all accessible displays, and notes that locked displays are skipped. It also mentions required scope. However, it does not explicitly compare with alternative tools for single-display or category-based broadcasting.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable detail: requires display.send capability, locked displays are skipped with a reason. This goes beyond annotations but could still elaborate on error handling or idempotence.

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

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

Three sentences, each focused and informative. No redundant or vague phrasing. Front-loads the core action and adds critical details sequentially.

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

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

Given the tool's complexity (7 parameters, output schema present), the description covers primary behaviors (send, dry-run, descendants), prerequisites (capability), and edge cases (locked displays). Output schema handles return details, so no further explanation needed.

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

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

With 71% schema coverage, the description adds meaning beyond schema descriptions, notably clarifying that html is required unless dry_run=true, and explaining include_descendants. Parameters like access_token and session_request_id are not mentioned, but the schema covers them.

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

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

The description clearly states the tool sends HTML to displays assigned to specific categories, with explicit mention of key options like include_descendants and dry_run. This distinguishes it from sibling tools like broadcast_content or send_html, which likely target individual displays or different scopes.

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

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

The description provides usage context: when dry_run is applicable, requirement for display.send capability, and behavior with locked displays. However, it does not explicitly contrast this tool with alternatives like broadcast_content or send_html, leaving the agent to infer the categorical focus.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context: the operation is owner-scoped (only touches caller's rows), does not mutate others' categories, and returns a per-display result list. No contradiction with annotations.

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

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

Two sentences: first states purpose and scope, second details scoping and return format. No wasted words. Front-loaded with the main action.

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

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

Given the 5 parameters, full schema coverage, and presence of an output schema, the description covers essential behavioral aspects (scoping, return format). It is sufficiently complete for an agent to understand the tool's purpose and usage constraints.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description does not add additional parameter semantics beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool bulk adds or removes a category across multiple displays, scoped to the caller's managed displays. It distinguishes from related tools like set_display_categories_for_display (single display) and create_display_category (category creation). The verb-resource combination is specific.

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

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

The description explains the owner-scoped behavior and that it doesn't affect other managers' assignments. It implies when to use (bulk operations on owned displays) but does not explicitly list when not to use or alternatives. Returns per-display results, which helps the agent understand the outcome.

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

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

Beyond the annotations (which only indicate non-readonly and non-destructive), the description adds critical behavioral details: the operation permanently transfers ownership, counts against the user's display quota, and requires admin scope. This gives the agent a clear understanding of the tool's effects and side effects.

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

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

The description is concise at four sentences, each serving a distinct purpose: definition, consequence, usage guidance, and return summary. It front-loads the core action and avoids redundancy. No wasted words.

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

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

Given the tool's complexity (ownership transfer, quota impact, admin scope) and the presence of a comprehensive input schema and output schema reference (mentions returning profileId and name), the description covers all essential aspects: purpose, prerequisites, consequences, and return values. No gaps remain.

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

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

The input schema already provides detailed descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds value by explaining the usage of access_token (prefer session_request_id) and giving an example for profile_name. This additional context justifies a score above baseline, though the schema itself is already informative.

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

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

The description clearly states the action ('Converts an unclaimed guest or pending display into a managed personal display') and the specific resource. It also distinguishes from the sibling tool pair_by_code by noting the appropriate use case ('For first-time physical setup, prefer pair_by_code instead'). The verb 'converts' and the object 'unclaimed guest or pending display' are specific and unambiguous.

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

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

The description explicitly states when to use the tool ('only when the user explicitly wants to adopt an existing hardware or demo display that is already running') and when not to use it ('For first-time physical setup, prefer pair_by_code instead'). It also mentions the requirement for admin scope, providing clear guidance on authorization prerequisites.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds behavioral details: 'Viewers will immediately see the change', 'Returns id and status ('cleared')', and required scope. No contradictions. The description enriches transparency beyond the annotations.

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

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

Three sentences, each serving a distinct purpose: action, usage context, differentiation and return info. No redundancy, front-loaded with the core verb and resource.

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

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

Given 2 parameters and a simple output, the description covers purpose, effect, alternative, authentication, and return format. No gaps. The agent has all necessary information to decide and invoke correctly.

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

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

Schema descriptions cover 100% of parameters (display_id format, access_token purpose). The description does not add new parameter semantics but reinforces the tool's effect. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description uses specific verbs ('removes current live content', 'returns to idle/default state') and explicitly distinguishes from delete_display ('does not delete the display itself'). This eliminates ambiguity and clearly defines 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.

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

The description states when to use the tool ('user wants to blank or reset a display') and explicitly tells when not to use it ('use delete_display for that'). It also mentions authentication scope requirements, providing complete usage guidance.

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

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

Annotations give readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds behavioral context beyond annotations by stating: 'Requires admin scope' and 'If the display is online, changes are pushed immediately via SignalR.' This informs the agent about authorization and real-time behavior. However, it does not explain the destructive nature (destructiveHint=true) further.

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

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

The description is four sentences long, each serving a clear purpose: purpose statement, usage guidance, optionality/behavior, and additional context (push, scope). No unnecessary words; every sentence earns its place.

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

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

Given the tool's complexity (9 parameters, many booleans/enums) and the presence of an output schema, the description covers essential aspects: admin scope, optional parameters, real-time push. It does not explain the return value or response format, but the output schema likely handles that. Slightly more detail about offline behavior or error conditions would improve completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by grouping parameters into categories (hardware permissions, UI settings) and explicitly stating that only provided parameters are changed (partial update behavior). This contextual information is not in the schema descriptions.

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

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

The description uses the specific verb 'updates' and clearly identifies the resource as 'hardware permission and UI settings for a display'. It enumerates the specific settings (camera, microphone, geolocation, etc.), making the tool's purpose unambiguous. This distinguishes it from sibling tools like 'create_display' or 'lock_display'.

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

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

The description explicitly states when to use the tool: 'Use this when the user wants to enable or disable...' and clarifies that 'All parameters except display_id are optional — only provided settings are changed.' It does not explicitly mention when not to use it or alternatives, but the guidance is clear and actionable.

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

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

Discloses that the raw key is returned only once (must be stored securely) and requires user consent. Adds value beyond annotations (readOnlyHint=false, destructiveHint=false) by explaining non-idempotency and security. Could mention rate limits or multiple key creation, but adequate.

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

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

Two sentences, no wasted words. Front-loaded with main purpose, followed by constraints. Every sentence earns its place.

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

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

Given an output schema exists, the description need not explain return values. Covers creation, security, consent, scope, and granular permissions adequately for a 9-parameter tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context about key storage and granular scoping, supplementing the schema descriptions. Adds value beyond the schema.

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

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

Clearly states the tool creates a long-lived API key for server-to-server integration without OAuth. Distinguishes from siblings like list_api_keys and revoke_api_key by specifying the use case.

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

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

Provides clear context for when to use (server-to-server without OAuth) and prerequisites (user consent, admin scope). Does not explicitly state when not to use or name alternatives, but the context is sufficient.

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

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

Annotations are present but basic. The description adds behavioral context: it creates a session (not read-only), requires user interaction (open loginUrl), and describes return fields including expiration. Does not contradict annotations.

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

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

Three sentences, front-loaded with purpose and usage. Every sentence provides essential information without redundancy.

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

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

Given the tool's simplicity (2 optional params, no nested objects) and presence of output schema details in description, it is fully complete. It covers parameters, return values, and workflow steps.

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

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

Schema coverage is 100% with good descriptions. The description adds minor extra context for agent_identifier ('shown to the user in the browser consent screen') but otherwise does not significantly augment parameter meaning.

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

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

The description clearly states it creates a browser-based login session and returns a loginUrl. It specifies the use case: when the client cannot complete OAuth 2.1 with PKCE. This distinguishes it from other auth tools like authenticate and get_auth_session.

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

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

Explicitly states when to use ('as the first step when your client cannot complete OAuth 2.1 with PKCE itself') and when not to use ('if you already have a valid Bearer token'). Also provides next steps (poll get_auth_session).

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

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

Annotations indicate non-destructive and non-read-only. Description adds context: display starts offline/uncoupled, requires admin scope, and contrasts with other tools' auth requirements.

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

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

Well-organized with conditional guidance and return fields listed. A bit long but each sentence adds value. Could be slightly more concise.

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

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

Complete for a creation tool with output schema. Covers when to use, alternatives, auth requirements, and return fields. No gaps.

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

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

Schema coverage is 100%. Description adds example for 'name' and explains when to use access_token vs. session_request_id. Adds meaning beyond schema.

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

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

The description clearly states the tool creates a personal display without pairing, and distinguishes it from pair_by_code. The verb 'create' and resource 'display' are specific.

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

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

Explicitly tells when to use this tool (pre-provisioning, headless) vs. pair_by_code, and warns not to use it for capacity checks (use get_account).

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

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

Annotations already indicate non-destructive behavior. The description adds valuable behavioral context: stable IDs and that renaming retains assignments/grants. It also states required capability. No contradiction with annotations.

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

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

Three sentences with no waste. First sentence states purpose, second adds subcategory nuance, third covers behavioral trait and requirement. Front-loaded and efficient.

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

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

Given 4 parameters, 1 required, and an output schema, the description covers creation purpose, subcategory usage, stability, and required capability. It lacks error handling (e.g., duplicate names) but output schema may compensate. Almost complete.

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

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

Schema coverage is 100%, so each parameter is described in the input schema. The description echoes the use of parent_category_id for subcategories but adds no new semantic value beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool creates a personal display category using specific verbs and resource. It distinguishes from siblings like rename_display_category and list_display_categories by specifying 'personal' and by focusing on creation.

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

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

It provides clear when-to-use guidance: create a personal display category, optionally with a parent_category_id for subcategories. However, it does not explicitly state when not to use or mention alternatives for organizational categories, though such a tool may not exist.

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

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

Discloses that the user becomes owner, requires admin scope, and lists return fields. Annotations already indicate mutation (readOnlyHint=false), so description adds valuable context without contradicting.

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

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

Three sentences with front-loaded main action. Every sentence adds value; no unnecessary text.

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

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

Given the output schema exists, the description covers creation, ownership, use case, scope, and returned fields. Could be slightly more complete with error handling or limits, but adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for the parameters.

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

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

Clearly states it creates a new organization and sets the authenticated user as owner. Distinct from sibling tools like list_organizations or delete_organization.

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

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

Explicitly says to use when setting up a shared display fleet, providing a clear use case. Lacks explicit mention of when not to use, but context is sufficient.

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

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

Annotations provide minimal behavioral info (not read-only, not destructive). Description adds significant context: display starts offline and uncoupled, owned by org not user, requires admin scope and manager role. No contradiction with annotations.

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

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

Description is well-structured with each sentence providing distinct value. Slightly verbose but every sentence earns its place. Front-loaded with purpose and key distinction.

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

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

Given the tool has only 3 parameters and an output schema exists, the description covers all needed context: state after creation, ownership, required permissions, and alternative tool guidance. No gaps for safe usage.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add significant extra meaning beyond what the schema already provides for the parameters. However, it does contextualize the need for available licenses and org_id source.

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

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

Clearly states it creates a display without pairing, distinguishing from pair_by_code. Uses specific verb 'creates' and explicit resource 'display in organization', with clear scope of offline/uncoupled state.

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

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

Explicitly says when to use (administrative pre-provisioning when screen not available) and when not (prefer pair_by_code for physical screens). Also lists prerequisites: admin scope, manager+ role, available licenses.

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

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

Beyond the destructiveHint annotation, the description adds that displays referencing deleted assets will show broken images and that content_only scope is required. This provides useful behavioral context not captured in annotations.

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

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

The description is two efficient sentences. The first states the primary action; the second adds critical side effects and requirements with no wasted words.

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

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

For a destructive multi-asset deletion tool with good annotations and an output schema, the description covers side effects and authentication adequately. Minor gap: does not clarify if deletion is permanent or reversible, but overall complete.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description does not add new semantic meaning beyond restating that asset_ids are the targets and access_token is optional.

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

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

The description clearly states the tool deletes one or more assets, specifying the action and resource. It distinguishes from siblings like update_asset or upload_asset by explicitly using 'deletes' and mentioning the side effect on referencing displays.

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

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

The description mentions the required authentication scope but does not provide when-to-use or when-not-to-use guidance relative to siblings. No alternatives or exclusions are mentioned, relying on the obvious destructive nature.

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

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

Adds beyond annotations: mentions that the readUrl will return 404 and that the action cannot be undone. These are critical behavioral traits not captured in annotations alone. No contradiction with annotations.

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

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

Four succinct sentences, each adding unique information: purpose, side effect, irreversibility, parameter guidance, authentication. No wasted words.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers the key aspects: what it does, side effect, irreversibility, parameter usage. Could mention success/failure response but output schema likely covers that.

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

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

Schema coverage is 100%, but description adds value by explaining the conditional usage of group_id (group vs personal slots) and requiring authentication. Does not redundantly repeat schema descriptions.

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

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

The description clearly states the tool's action (permanently deletes a data slot) and distinguishes it from siblings like set_data_slot and get_data_slot. It explicitly mentions the irreversible nature and side effect on the readUrl.

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

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

Provides clear instruction on when to use the group_id parameter (for group slots) and when to omit it (personal slots). Requires authentication is stated. Does not explicitly state when not to use this tool, but the purpose implies exclusivity.

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

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

The description reinforces the destructiveHint annotation by stating the action is permanent and cannot be undone. It adds the requirement for admin scope, providing behavioral context beyond the annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core action and immediately addresses usage guidance and output.

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

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

Given the destructiveHint annotation and the presence of an output schema, the description covers the essential aspects: action, permanence, usage recommendation, permission requirement, and return values. No gaps remain.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add additional meaning beyond what's in the schema, achieving the baseline score.

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

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

The description clearly states it permanently deletes a display and all associated content. It uses a specific verb ('deletes') and resource ('display'), and distinguishes from sibling tools like 'clear_display' or 'remove_display_from_org'.

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

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

The description advises using only when the user explicitly confirms removal and notes the requirement for admin scope. While it doesn't enumerate alternatives or when-not-to-use, the context is clear and sufficient for an agent.

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

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

Annotations provide destructiveHint=true. Description adds context about permanent deletion, effect on displays and members, and irreversibility, going beyond annotations.

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

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

Three sentences, front-loaded with purpose, then authorization, then irreversibility. No wasted words.

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

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

Covers purpose, effect, authorization, irreversibility. Output schema exists, so return values not needed. Misses error conditions or prerequisites like org being empty, but overall complete for a delete tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no parameter-specific information beyond the schema, but the schema already describes them adequately.

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

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

The description clearly states the verb 'deletes', the resource 'organization', and the effects on displays and members. It distinguishes itself from sibling tools like create_organization, rename_organization, and delete_display.

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

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

Specifies prerequisites: 'Only the owner can delete' and 'Requires admin scope'. However, it does not explicitly mention when not to use or compare to alternatives like remove_member for deconstructing an org.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds meaningful behavioral context: authentication requirements for public vs private URIs and the return fields (uri, type, title, text, data).

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

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

Three concise sentences: first states purpose, second provides usage flow, third adds authentication and return details. No wasted words, effectively front-loaded.

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

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

With only one parameter and an output schema present, the description adequately covers authentication, usage pattern, and return fields. Sufficient for an agent to understand tool behavior.

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

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

The schema description coverage is 100%, and the description reiterates the same information about the URI parameter. It adds no new meaning beyond the schema, thus baseline score of 3.

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

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

The description clearly states the verb 'Retrieves', the resource 'full details of a single agentView resource', and distinguishes from search tools by specifying after search or direct URI usage.

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

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

The description provides explicit usage scenarios ('Use this after search... or directly when you already know the URI') and differentiates between public/private URIs with authentication requirements, but lacks explicit when-not-to-use guidance or alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety profile is clear. Description adds behavioral context like 'Requires authentication with at least content_only scope' and details the return fields, which helps the agent understand the tool's behavior beyond annotations.

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

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

Single paragraph is well-structured with purpose, field list, usage guidance, and exclusion instruction. Slightly verbose but every sentence adds value; minor reduction could improve conciseness.

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

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

Given that an output schema exists (though not shown), the description is comprehensive: explains return fields, usage context, auth requirements, and explicitly excludes misuse. No gaps for a simple get-profile tool.

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

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

Schema covers access_token with 100% coverage. Description adds valuable usage semantics: explains when to use access_token vs session_request_id and that the server resolves authentication. This goes beyond the schema's description.

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

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

Description clearly states 'Returns the authenticated user's account profile' and enumerates specific fields (userId, name, email, plan, display limits, etc.). Explicitly distinguishes from sibling by saying 'Do not use this to list displays — use list_displays instead.'

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

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

Provides explicit guidance: 'Use this to answer questions about the user's subscription, display quota, organization memberships or plan capabilities.' Also gives a clear when-not-to-use instruction referring to the sibling tool list_displays.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds detail about returning URL and authentication requirement, but does not significantly extend beyond annotations.

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

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

Two sentences with no wasted words. Purpose is front-loaded, and the description is efficiently structured.

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

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

For a simple read-only single asset retrieval tool, the description, annotations, and output schema provide complete context. No missing information for correct invocation.

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

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

Input schema has 100% coverage with descriptions for both parameters. The description does not add further semantic meaning beyond that already in the schema.

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

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

The description clearly states it returns metadata for a single asset including its URL, and provides a specific use case (verifying asset existence). This distinguishes it from siblings like list_assets or update_asset.

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

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

It specifies when to use the tool (to verify existence before referencing) and the required authentication scope. It does not explicitly state when not to use, but the context is sufficient for selection.

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

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

Annotations indicate idempotence and non-destructive behavior. The description adds significant behavioral context: polling frequency, three possible states and their meanings, security note about bearer token not being returned, and automatic authentication on active status.

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

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

The description is somewhat long but every sentence adds value. It is front-loaded with the core purpose and well-structured. Could be marginally more concise but still efficient.

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

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

Given the presence of an output schema, the description adequately explains return states and actions to take. It completes the context of the auth workflow, including when to poll and how to handle each result.

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

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

Only one required parameter with 100% schema coverage. Description adds value by emphasizing that the session_request_id must be passed exactly as received, which is a critical usage detail beyond the schema.

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

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

The description clearly states it polls the status of a login session created by create_auth_session. The verb 'polls' and resource 'login session status' are specific, and the tool is distinguished from siblings by being part of the auth flow only.

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

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

Explicitly states to use after create_auth_session, poll every 2-3 seconds until status is not 'pending', and not for any other purpose. Also provides guidance on reauthentication if expired.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by noting the readUrl in the response and authentication requirement, adding behavioral context beyond annotations.

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

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

Three sentences with clear front-loading of purpose, followed by usage hint and response detail. No superfluous words; every sentence serves a purpose.

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

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

Given the presence of an output schema, the description adequately covers purpose, parameter usage, response feature (readUrl), and authentication. No gaps for this read-only, idempotent tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful interpretation for group_id ('omit for personal slots'), enhancing understanding beyond the schema's description.

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

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

The description clearly states 'Returns the current JSON content and metadata of a data slot by slug,' specifying a verb and resource. It distinguishes this tool from siblings like set_data_slot, delete_data_slot, and list_data_slots, which have different actions.

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

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

Provides explicit guidance on using group_id for group slots and omitting for personal slots. Mentions authentication requirement. Lacks explicit 'do not use when' statements, but context is clear given sibling names.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: results capped at 50 with 'truncated' flag, same read scope required, and caveat about personal/group slot scope. No contradiction.

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

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

The description is a single paragraph with clear sentences covering purpose, usage, scope, limits, and auth. It is not overly verbose, though it could be broken into shorter sentences for easier scanning. Every sentence adds value.

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

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

Given the tool's complexity (3 parameters, no nested objects, output schema exists), the description covers all critical aspects: what is returned (displays with placeholders), the limit and truncation behavior, auth and scope requirements, and the connection to sibling tools. No gaps.

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

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

Input schema has 100% coverage for all three parameters with descriptions. The description adds little beyond schema: it explains the slug parameter's purpose ('scan usage for') and the group_id parameter's role ('for group slots'), but the schema already covers these. Baseline 3 is appropriate.

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

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

The description clearly states it lists displays that embed a {{slot:<slug>}} placeholder for a specific data slot. It uses a specific verb ('Lists') and resource ('displays'), and distinguishes from siblings like get_data_slot (which retrieves slot data) and delete_data_slot (which needs this info beforehand). No ambiguity.

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

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

Explicitly states when to use: 'Use this BEFORE delete_data_slot to know which displays will start returning 404, or before set_data_slot on a structural change.' Also covers scope differences (personal vs group). Provides clear guidance on alternatives and prerequisites.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by detailing the return contents and authentication requirement, but does not contradict annotations. A score of 4 reflects that annotations carry most transparency burden, description adds context.

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

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

Three sentences: first states what the tool returns, second gives usage guidance, third authentication. No extraneous words. Front-loaded with key information.

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

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

Given the output schema exists and annotations are comprehensive, the description covers purpose, usage, authentication, and return contents. It is fully complete for a read-only retrieval tool.

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

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

Input schema coverage is 100%, so baseline is 3. The description adds no parameter details beyond the schema, but that is acceptable since schema is complete.

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

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

The description clearly states that the tool returns full details of a single display, and enumerates many specific aspects (live state, content, pairing links, etc.). It distinguishes itself from list_displays (discovery) and create_display (creation).

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

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

Explicitly says when to use ('when you already know the display ID and need its complete state') and when not to ('do not use this to discover displays — use list_displays first'). Also specifies required authentication scope.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds significant behavioral context: requires content scope, owner permissions, and explains substitution behavior including unresolved placeholders. No contradiction with annotations.

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

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

The description is a single efficient paragraph (~150 words), front-loaded with the main purpose, then a killer flow example, followed by requirements and edge cases. Every sentence earns its place with no repetition of schema content.

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

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

Given the presence of an output schema (not shown but indicated), the description appropriately focuses on usage context. It covers the substitution mechanism, unresolved placeholders, and authentication preferences. It is complete enough for a read-only artifact retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to discover artifact keys (via get_store_template_details) and clarifying that session_request_id is preferred over access_token. This goes beyond the schema descriptions.

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

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

The description uses a specific verb- resource pair: 'Returns the agent-onboarding artifact body... SUBSTITUTED against the slot slugs'. It clearly distinguishes from sibling tools like get_store_template_agent_artifact by emphasizing substitution and giving a concrete use case.

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

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

Provides a clear usage flow ('Add my Claude Code agent...' → list_displays → get_display_agent_artifact → save) and mentions prerequisites (content scope, ownership/API-key). However, it does not explicitly compare with the similar sibling tool get_store_template_agent_artifact, so misses an opportunity for when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context that the tool returns resolved capabilities and lists many specific fields, confirming it is a read-only operation. No contradictions. Adds value by detailing the output content.

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

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

Two sentences: first succinctly lists all returned data categories, second provides usage guidance and auth requirement. No extraneous words, front-loaded with essential information.

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

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

For a read-only tool with an output schema, the description adequately covers what it returns and when to use it. The presence of an output schema means return values are documented elsewhere, so the description is complete without explaining them.

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

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

Schema coverage is 100% with all three parameters described in the input schema. The description does not add any additional meaning about parameters beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and identifies the resource as 'resolved display capabilities', listing concrete facts like screen, viewport, browser version, etc. It distinguishes from siblings like get_display by focusing on capabilities needed for content matching.

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

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

Explicitly states when to use: 'Call this before generating or sending HTML so your agent can match the content to the real display browser.' Also notes authentication requirement. Does not specify when not to use or contrast with alternative tools, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scope requirement and return data specifics, but does not detail additional behaviors (e.g., rate limits, caching). Still adds value beyond annotations.

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

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

Description is a single paragraph but front-loaded with main purpose. Includes multiple guidance points efficiently. Could be more structured (e.g., bullet points) but is not verbose.

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

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

Given output schema exists, description adequately covers return data, usage guidance, and scope. No missing elements for a read-only tool with good annotations.

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

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

Schema coverage is 100% with descriptions for both parameters. Description does not add new parameter context beyond the schema; baseline 3 is appropriate.

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

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

Clearly states it returns current content state of a display, listing specific fields (active live content, content URL, idle content, delivery status). Distinguishes from siblings read_display_html and get_display_preview_url.

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

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

Explicitly advises checking currentContentDescription first, using read_display_html only for raw source edits, and using get_display_preview_url for sharing. Also mentions required scope 'content_only'.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint=true, destructiveHint=false): short-lived, read-only, expires after ttl_seconds, dies on owner push, TTL clamping based on privacy_mode, and that recipients cannot push/configure/discover. No contradiction with annotations.

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

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

The description is dense and well-structured in a single paragraph with logical flow. Every sentence adds value, but could be slightly more concise given the length (5 sentences).

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

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

Given the complexity (3 parameters, output schema exists, annotations present), the description is comprehensive, covering behavior, constraints, usage context, and scope requirement. The output schema is present but not described, which is acceptable per rules.

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

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

Schema coverage is 100%, but the description enriches all three parameters: display_id format, ttl_seconds defaults and clamping behavior, and access_token as optional JWT. The description adds meaning beyond the schema constraints.

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

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

The description clearly states the tool 'generates a short-lived signed share link for the display's CURRENT content', specifying the verb 'generates' and resource 'share link', and distinguishes itself from siblings by emphasizing it's the only supported way to share screen content.

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

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

The description provides explicit when-to-use scenarios: 'when the user wants to send what the screen is showing to a colleague, embed it in a chat or document, or hand it to an external integration.' It also notes that the legacy URL is removed for GDPR compliance, but it does not explicitly state when not to use this tool.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds the requirement for 'content_only scope' and specifies the return content, providing useful context beyond annotations.

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

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

Two sentences, highly concise, front-loaded with the primary action and followed by usage guidance. No wasted words.

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

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

Given the existence of an output schema, the description sufficiently covers what the tool returns. It also explains the purpose and prerequisites, making it complete for a read-only info tool.

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

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

Schema coverage is 100% and the only parameter is an optional access_token, which is self-explanatory. The description does not add any additional meaning beyond the schema.

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

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

The description clearly states it returns 'complete license allocation overview' and enumerates specific fields (total premium licenses, personal usage, etc.), distinguishing it from sibling tools like allocate_licenses which actually modify licenses.

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

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

Explicitly advises 'Use this to understand available capacity before allocating licenses,' giving clear context for when to use. It also mentions the required scope, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations by specifying that authentication with at least content_only scope and user membership in the organization are required. No contradictions.

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

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

Three sentences: first states purpose, second gives usage guidance, third covers auth. Every sentence is necessary and informative. No fluff, front-loaded.

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

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

Given the presence of an output schema and the tool's simplicity (get a specific org), the description is complete. It covers purpose, usage context, and auth requirements. No missing critical information.

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

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

Schema coverage is 100% with both parameters (org_id, access_token) well-documented. The description does not add additional semantic meaning beyond the schema, as it only mentions auth requirements which are not parameter-specific. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns full details of a specific organization including displays, members, roles, slots, and capacity. It distinguishes from sibling tool list_organizations by emphasizing 'specific organization' and 'inspect a specific organization's state'.

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

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

Explicitly says 'Use this after list_organizations to inspect a specific organization's state', providing clear when-to-use guidance. It also states authentication and membership requirements. Does not mention when not to use or alternatives beyond list_organizations.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, indicating safe, read-only behavior. The description adds that no authentication is required and specifies the returned fields, but this adds marginal value beyond the annotations.

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

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

The description is concise with two sentences. The first sentence states the action and outputs, and the second gives usage context. No unnecessary words, front-loaded, and efficient.

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

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

Given the tool's simplicity (no parameters, rich annotations, and an output schema), the description is fully sufficient. It covers what the tool does, when to use it, and key behavioral details (no auth required). No gaps.

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

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

The tool has no parameters and schema coverage is 100% (empty). Since there are no parameters to explain, the description does not need to add parameter semantics. Baseline score of 4 is appropriate for zero parameters.

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

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

The description clearly states the tool returns the server's public readiness status, version string, and discovery URLs. It specifies the verb 'Returns' and the resource, distinguishing it from other tools that require authentication or have different purposes.

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

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

The description explicitly states to use this tool before authenticating to verify server reachability and obtain entry-point URLs. It also notes that no authentication is required, providing clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds critical context: data slots and uploads share one quota, and suppression of numbers for certain API keys with suppressed=true flag. No contradiction with annotations.

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

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

Two sentences: first states main action and scope, second adds usage guidance and edge case. Front-loaded, no redundancy, every sentence earns its place.

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

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

Given output schema exists, description doesn't need to detail return fields. It covers key behavioral aspects (shared quota, suppression) and usage scenario, making it complete for agent decision-making.

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

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

Schema description coverage is 100%. Description largely repeats schema parameter descriptions (group_id, access_token) without adding new meaning. Baseline 3 is appropriate since schema already covers parameters adequately.

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

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

Description clearly states the tool returns storage-pool snapshot (used/limit/remaining bytes) for personal or group scope. Specific verb and resource, distinguishes from related tools like set_data_slot and upload_asset by recommending its use before them.

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

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

Explicitly tells when to use: before set_data_slot or upload_asset on large payloads to avoid 413 errors. Also explains suppression behavior for narrowly-scoped API keys, giving clear context for when normal results are available.

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

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

Annotations indicate readOnly, non-destructive, idempotent. Description adds key behavioral facts: 'Placeholders are NOT substituted' and 'No authentication required', which are beyond annotation scope. It does not mention error cases or rate limits, but for a simple read-only operation, this is sufficient.

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

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

Three sentences, each serving a distinct purpose: action, placeholder clarification, and guidance. Front-loaded with core function. No unnecessary words.

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

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

Given the output schema exists, the description need not detail return format. It explains raw vs. substituted, directs to sibling tools for keys and post-install use, and confirms no auth required. For a read-only retrieval tool, this is fully complete.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds examples for key ('bot-system-prompt', 'agent-skill') and context about slug as template slug, but does not add significant meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns the RAW body of an artifact from a store template, with specific examples (system prompt, SKILL.md). It distinguishes itself from sibling get_display_agent_artifact by noting it does not substitute placeholders. The verb 'Returns' and resource 'RAW body' are specific.

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

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

Explicitly says to use BEFORE installation when no display exists, and to use get_display_agent_artifact after installation. Also references get_store_template_details for discovering artifact keys. This is clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that only the current published version is returned and that no authentication is required, providing additional behavioral context beyond annotations.

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

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

The description is three sentences, well-structured: first sentence states what it returns, second explains placeholders, third covers version and auth. It is reasonably concise but could be slightly tighter.

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

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

Given the output schema exists and schema coverage is high, the description covers key points: return data shape, placeholder behavior, version handling, and auth. It references sibling tool for slot shape, which adds context. No major gaps identified.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining placeholder resolution (assets to URLs, slots left intact) and that version mismatch returns specific errors, providing meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the function: 'Returns the raw display HTML body of a published store template plus its static slot definitions and allowed external origins'. It specifies the verb 'Returns' and the resource (store template content). It distinguishes from siblings by mentioning the slots array shape referencing get_store_template_install_options.

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

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

The description explains the tool is for inserting a template as an editable slide and clarifies placeholder handling (resolved assets vs intact slots). It implicitly distinguishes from get_store_template_install_options by referencing its data shape, but does not explicitly state when not to use this tool or provide direct alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. Description adds 'No authentication required' and details the agentArtifacts metadata-only nature, linking to related endpoints. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that front-loads the key output. It is detailed but not excessively long. Minor improvement would be breaking into multiple sentences for readability.

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

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

Given output schema presence, the description needn't detail return types, but it does so anyway. It also explains the relationship with two artifact endpoints, covering the full context for using this tool in a workflow.

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

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

Schema coverage is 100%. The description adds useful context: slug format 'English kebab-case returned by search_store_templates' and language defaults/enum values. This enriches the schema without redundancy.

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

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

The description explicitly states it returns 'full public details of a single store template' and enumerates the fields (title, description, markdown, category, etc.), clearly distinguishing it from sibling tools like search_store_templates and the artifact retrieval tools.

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

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

Provides explicit guidance: 'Use this after search_store_templates picks a candidate' and explains how the result drives decisions (explain template, check for agent integration, choose install flow). Implicitly advises against using it to get artifact bodies.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: authentication scope requirements (content_only), scoping behavior for API-key callers (only see whitelisted displays), and a user-facing fallback instruction. No contradiction with annotations.

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

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

The description is a single paragraph of four sentences, front-loaded with purpose and usage. It is concise without being terse. Could be slightly more structured (e.g., bullet points), but it efficiently conveys all necessary information.

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

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

Given the presence of an output schema (as indicated by context signals), the description does not need to detail return values. It covers authentication, scoping, error handling (no displays), and references sibling tools. This is complete for a read-only query tool.

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

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

Schema coverage is 100% with descriptive field descriptions. The description only adds minimal value for the 'slug' parameter by referencing search_store_templates and giving an example. For the other parameters, the description does not add meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns displays and data slots for a store template, with a specific verb ('Returns') and resource ('displays... plus data slots'). It distinguishes itself from the sibling send_store_template_to_display by explicitly noting this is a prerequisite call.

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

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

Explicitly says 'Call this before send_store_template_to_display', provides context on authentication (content_only scope, API-key scoping), and instructs what to do when no displays are returned (tell user to create/claim a display, referencing sibling tools create_display and pair_by_code). This provides comprehensive when-to-use and when-not-to guidance.

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

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

The description reveals key behaviors: invite validity period (7 days), email binding, auth requirements, and return value (inviteUrl). This adds context beyond annotations (which include destructiveHint=true, but description does not contradict).

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

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

The description is three sentences, efficient and front-loaded with the primary purpose. Every sentence adds necessary detail without redundancy.

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

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

Given the tool's complexity (4 parameters, output schema exists), the description covers creation, validity, requirements, and return value. It is complete for the agent to understand when and how to use it.

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

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

With 100% schema coverage, the description adds value by clarifying the email parameter's purpose ('only that person can accept'), role valid roles, and org_id source. Some parameters like access_token are not elaborated, but the schema already documents them.

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

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

The description clearly states it creates an invite link to add a member to an organization, using specific verbs and resources. It distinguishes from sibling tools like 'remove_member' and 'update_member_role' by its focus on invitation.

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

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

The description specifies prerequisites (admin scope, admin/owner status) and optional email binding, but does not explicitly mention when not to use it or suggest alternative tools. Still provides clear context for invocation.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds valuable behavioral context: it never returns the raw key (security) and requires admin scope (access control), which goes beyond the annotations.

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

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

Two sentences, front-loaded with the main action, no unnecessary words. Every sentence adds value.

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

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

Given that an output schema exists (not shown), the description does not need to detail return values. It covers purpose, key behaviors, security, and prerequisites, making it complete for a list tool.

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

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

The single optional parameter 'access_token' is fully described in the input schema (100% coverage). The description does not add additional parameter details, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Lists', the resource 'API keys', and the scope 'for the current user'. It specifies what metadata is returned and explicitly notes security (never raw key) and required scope, distinguishing it from siblings like create_api_key and revoke_api_key.

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

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

The description mentions 'Requires admin scope' as a usage condition but does not explicitly state when to use this tool versus alternatives like create or revoke API keys. The context of listing is implied but not contrasted with other tools.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds that it returns URLs, requires content_only scope, and can be used for duplicate checking, providing useful behavioral context beyond annotations.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds value. No fluff or redundancy.

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

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

With an output schema present and good annotations, the description covers essential context: scope requirements, duplicate checking, and filter options. Could slightly improve by mentioning pagination behavior (limit default) which is in schema but not in description.

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

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

Schema coverage is 100% with each parameter described. The description summarizes the filter options but does not add new meaning beyond the schema. Access_token is not mentioned in the description but is covered in the schema.

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

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

The description clearly states the tool lists assets for the authenticated user with optional filtering, and returns asset URLs. It differentiates from siblings like upload_asset, delete_asset, and get_asset by specifying its listing function.

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

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

Explicitly advises checking before uploading to avoid duplicates and mentions required authentication scope. However, it does not explicitly state when not to use this tool or mention alternatives like search for broader queries.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that returns metadata only (no jsonContent) and includes readUrl, along with authentication requirement. This enriches understanding beyond annotations without contradiction.

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

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

Three sentences, no fluff. Front-loads the main action ('Lists data slots with optional filtering') and efficiently conveys key behavioral details in a structured manner.

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

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

Given good schema descriptions, annotations, and existence of output schema, the description sufficiently covers behavior and usage. Lacks explicit mention of pagination behavior or distinction from single-slot retrieval, but overall complete for a list tool.

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

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

All 5 parameters have descriptions in the input schema (100% coverage), so baseline is 3. The description only mentions 'optional filtering' generally, without adding new details about parameters beyond what schema provides. No extra semantic enrichment.

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

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

Description clearly states it lists data slots with filtering, returns metadata only (no content), and includes readUrl. It effectively distinguishes from sibling tools like get_data_slot (single slot retrieval) and set_data_slot (write operation) by specifying scope and content type.

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

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

The description provides clear context: use for metadata and readUrl without content, requires authentication. However, it does not explicitly state when not to use or suggest alternatives like get_data_slot for a single slot or set_data_slot for writing, but the intent is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the tool is clearly safe. Description adds value by specifying what data is returned (stable IDs, paths, assignment counts) and the required permissions. No contradictions.

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

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

Two sentences: first states the core function, second provides usage guidance. No superfluous words. Front-loaded with the most important information.

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

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

Tool is a simple list operation. Description covers purpose, returned data, usage context, and auth requirements. Output schema exists (not shown but present), so return values are documented. No gaps for the task.

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

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

Schema coverage is 100% with both parameters (access_token, session_request_id) described. Description does not add extra parameter-specific semantics beyond the schema, but the authentication scope context is indirectly relevant. Baseline 3 is appropriate.

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

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

Description states 'Lists the authenticated user's personal display categories with stable IDs, paths and assignment counts.' Clear verb 'lists' and resource 'display categories' with explicit output details. Differentiates from siblings like create_display_category or rename_display_category.

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

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

Explicitly states 'Use this to discover existing categories before assigning or replacing categories on a display.' Provides clear context and purpose. Also mentions authentication scope and capability requirements, aiding correct invocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying required authentication scope (content_only, admin not required) and detailing the structure of each display entry, including runtime summary fields.

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