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

The description adds valuable context beyond what annotations provide: it explains the purpose of checking API key permissions and the specific access level being verified. While annotations already indicate this is a read-only, non-destructive operation, the description provides the 'why' behind the tool's existence and clarifies what 'password access' means in this 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?

Perfectly structured with three concise sentences: first states the purpose, second provides usage context, third specifies the return value. Every sentence earns its place with no wasted words, and the most important information (what the tool does) is 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?

For a simple permission-checking tool with no parameters, comprehensive annotations, and no output schema, the description provides exactly what's needed: clear purpose, usage guidance, and return value specification. It doesn't need to explain parameters or complex behaviors since the tool is straightforward and well-supported by 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?

With 0 parameters and 100% schema description coverage, the baseline would be 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on explaining the tool's purpose and return value, which adds meaningful context for a parameterless tool.

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 specific action ('check if the configured API key has password access permission'), identifies the resource (IT Glue API key configuration), and distinguishes this tool from all sibling tools which perform CRUD operations on various IT Glue entities rather than checking API permissions.

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 this tool ('before attempting password operations') and provides clear context about why it's needed (API keys can be configured with or without password access). This gives the agent specific guidance on when this verification step should be performed.

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 this is a non-destructive write operation (readOnlyHint: false, destructiveHint: false), which the description doesn't contradict. The description adds minimal behavioral context by specifying it creates 'a new configuration' and mentions the return value, but doesn't cover important aspects like authentication requirements, rate limits, or what happens on duplicate entries. With annotations covering safety, this is adequate but not rich.

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

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

The description is front-loaded with the core purpose, but the Args section is redundant with the schema and includes incomplete parameter information. The structure is clear but contains wasted space repeating schema details without adding value, making it less efficient than it could be.

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 creation tool with 22 parameters, no output schema, and annotations covering basic safety, the description is minimally adequate. It states the purpose and return value, but lacks guidance on usage, error handling, or detailed behavioral context. The high parameter count and mutation nature suggest more completeness would be beneficial, but annotations help bridge some 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 description coverage is 100%, so the schema fully documents all 22 parameters. The description lists only 16 parameters in its Args section, omitting several from the schema (e.g., default_gateway, location_id), and doesn't add any meaningful semantic context beyond what's already in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the verb ('Create') and resource ('new configuration (device/asset) in IT Glue'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'itglue_create_contact' or 'itglue_create_flexible_asset' beyond the resource name, which is why it doesn't reach a perfect score.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing organization_id from list_organizations), when to choose configuration vs flexible_asset, or any exclusions. The agent must infer usage from the tool name alone.

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

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

Annotations indicate this is a non-readOnly, non-destructive, non-idempotent, open-world operation. The description adds that it 'Returns: The created contact,' which provides useful output context beyond annotations. However, it lacks details on permissions, error conditions, or rate limits, leaving behavioral gaps despite the annotations covering basic safety.

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

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

The description is front-loaded with the core purpose, followed by a structured Args section and a Returns note. It's appropriately sized, but the Args section repeats schema information without adding value, slightly reducing efficiency. Overall, it's well-structured with minimal waste.

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 creation tool with 11 parameters, no output schema, and annotations covering basic traits, the description is adequate but incomplete. It specifies the return but lacks details on response structure, error handling, or dependencies (e.g., organization_id must exist). Given the complexity, more contextual information would be beneficial.

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 fully documents all parameters. The description lists parameters but adds no additional meaning beyond the schema (e.g., explaining what 'contact_type_id' represents or how arrays are structured). This meets the baseline for high schema coverage but doesn't enhance parameter understanding.

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

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

The description clearly states the specific action ('Create a new contact') and resource ('in IT Glue'), distinguishing it from sibling tools like itglue_get_contact, itglue_list_contacts, and itglue_update_contact. The verb 'Create' precisely indicates a write operation, making the purpose unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing organization), exclusions (e.g., not for updating contacts), or refer to sibling tools like itglue_update_contact for modifications. Usage context is implied but not explicitly stated.

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

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

Annotations indicate this is a write operation (readOnlyHint: false) with open-world semantics (openWorldHint: true) and is non-destructive. The description adds valuable context about the creation workflow and prerequisite tools, though it doesn't mention rate limits, authentication needs, or error behaviors beyond what annotations provide.

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

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

The description is well-structured and front-loaded with the core purpose, followed by prerequisite guidance and parameter notes. Every sentence serves a clear purpose with zero wasted words, making it efficient for an AI agent to parse.

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 creation tool with no output schema, the description provides adequate context about prerequisites and basic return information ('The created flexible asset'). However, it could be more complete by describing what happens on duplicate creation attempts or error scenarios, given the annotations show it's non-idempotent.

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 schema already documents all parameters thoroughly. The description adds minimal value beyond the schema, briefly mentioning that traits use 'field name-keys' and response_format options, but doesn't provide additional syntax or format details.

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 specific action ('Create a new flexible asset') and resource ('in IT Glue'), distinguishing it from sibling tools like itglue_update_flexible_asset or itglue_get_flexible_asset. It precisely identifies the operation without being tautological.

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 provides when-to-use guidance by naming two prerequisite tools (itglue_list_flexible_asset_types and itglue_list_flexible_asset_fields) that must be used first to obtain required IDs and field information. This gives clear context for proper tool sequencing.

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 this is a non-readOnly, non-destructive, non-idempotent, open-world operation. The description adds that it 'creates' something, which aligns with annotations (no contradiction), and mentions the return value ('The created location'), providing some behavioral context. However, it doesn't disclose important traits like potential side effects, authentication requirements, rate limits, or error conditions that aren't covered by annotations.

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

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

The description is front-loaded with the core purpose, but the parameter listing is redundant with the schema and adds unnecessary length. The structure could be more efficient by omitting the Args section and focusing on value-added information. However, it's not overly verbose, and the main point is clear upfront.

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 (13 parameters, creation operation) and rich schema coverage (100%), the description is minimally adequate. It states the purpose and return value, but lacks output details (no output schema), error handling, or integration context with siblings. Annotations cover basic behavioral hints, but for a creation tool, more guidance on usage and consequences 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 description coverage is 100%, meaning all parameters are documented in the schema itself. The description lists parameters but merely repeats what's in the schema without adding meaningful context (e.g., explaining relationships like region_id vs. country_id, or what 'primary' means functionally). Since the schema does the heavy lifting, the baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('Create') and resource ('new location in IT Glue'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other 'create' siblings like itglue_create_organization or itglue_create_contact, which would require specifying what makes a 'location' distinct from those other resources.

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 no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing an existing organization), when not to use it, or how it relates to sibling tools like itglue_update_location or itglue_get_location. The agent must infer usage from the tool name alone.

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

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

Annotations already indicate this is a write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds valuable context by specifying the return value ('The created organization with its new ID'), which helps the agent understand the outcome. However, it doesn't mention potential side effects, authentication requirements, or rate limits.

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

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

The description is well-structured with a clear purpose statement followed by parameter and return value sections. It's appropriately sized for an 8-parameter tool, though the parameter listing could be considered redundant given the comprehensive schema.

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 creation tool with good annotations (readOnlyHint: false, openWorldHint: true) and 100% schema coverage, the description provides adequate context. It explains the action and return value, though it could benefit from mentioning potential constraints or error conditions. The lack of output schema is partially compensated by the return value 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 description coverage is 100%, so the input schema already documents all parameters thoroughly. The description lists parameters but doesn't add meaningful semantic context beyond what's in the schema (e.g., explaining what organization_type_id values mean or how alerts are used). Baseline 3 is appropriate when 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 clearly states the specific action ('Create a new organization') and resource ('in IT Glue'), distinguishing it from sibling tools like 'itglue_update_organization' or 'itglue_list_organizations'. It precisely identifies the tool's function without ambiguity.

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

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

The description implies usage context (creating new organizations) but doesn't explicitly state when to use this tool versus alternatives like 'itglue_update_organization' or 'itglue_list_organizations'. No guidance is provided about prerequisites, dependencies, or exclusion scenarios.

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 this is a non-readOnly, non-destructive, non-idempotent, open-world operation. The description adds minimal behavioral context beyond this, only noting it 'Returns: The created password entry.' It doesn't disclose authentication requirements, rate limits, or error conditions, but doesn't 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?

The description is appropriately sized with a clear purpose statement followed by a parameter list. However, the 'Args' section is redundant given the schema, and the structure could be more front-loaded with critical usage information rather than parameter details already covered elsewhere.

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 creation tool with no output schema, the description adequately covers the basic purpose but lacks important context. It doesn't explain what the return value contains, error handling, or how this tool relates to siblings. Given the annotations provide safety information, this is minimally complete but could be more informative.

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 input schema already documents all parameters thoroughly. The description's 'Args' section merely repeats what's in the schema without adding meaningful context about parameter relationships, constraints, or examples. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Create a new password entry') and resource ('in IT Glue'), distinguishing it from sibling tools like itglue_get_password or itglue_list_passwords. It explicitly identifies the tool's function without being tautological.

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 no guidance on when to use this tool versus alternatives like itglue_update_password or itglue_check_password_access. It lacks context about prerequisites, appropriate scenarios, or exclusions, leaving the agent without usage direction.

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 this is a read-only, non-destructive, idempotent operation with open-world semantics. The description adds valuable context by specifying the types of detailed information returned (hardware details, network info, warranty status, related resources) and mentioning the optional 'response_format' parameter, which provides behavioral insight 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 efficiently structured with a clear purpose statement, bullet-point parameter explanation, and return value mention. Every sentence serves a purpose without redundancy, and it's appropriately sized for a tool with three parameters.

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 retrieval tool with comprehensive annotations and full schema coverage, the description provides adequate context about what information is returned and parameter usage. The main gap is the absence of an output schema, but the description compensates by mentioning the return format options and types of details included.

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 schema fully documents all parameters. The description adds minimal value by briefly mentioning the 'include' parameter for related resources and the return format options, but doesn't provide additional semantic context beyond what's 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 clearly states the verb ('Get') and resource ('a single configuration by ID'), distinguishing it from sibling tools like 'itglue_list_configurations' which returns multiple items. It specifies this is for retrieving detailed information about a specific device/asset, making the purpose unambiguous.

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

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

The description implies usage context by stating it retrieves 'detailed information' for a specific ID, suggesting it should be used when you need comprehensive data about one configuration rather than listing multiple. However, it doesn't explicitly mention when to use alternatives like 'itglue_list_configurations' for bulk retrieval or 'itglue_update_configuration' for modifications.

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

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

Annotations provide comprehensive hints (readOnly, openWorld, idempotent, non-destructive), so the description doesn't need to repeat safety aspects. It adds value by specifying the return content ('Contact details including emails, phones, and notes') and output format options, but doesn't disclose rate limits, authentication needs, or error behaviors beyond what annotations cover.

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

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

The description is well-structured and concise: a clear purpose statement followed by Args and Returns sections. Every sentence adds value, with no redundant information. It could be slightly more front-loaded by integrating the return details into the main statement, but overall it's 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 (2 parameters, no output schema), annotations cover safety, and schema covers parameters fully, the description provides adequate context. It specifies the return content and format options, which compensates for the lack of output schema. For a read-only get operation, this is reasonably complete, though it could mention error handling or authentication.

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 clear parameter documentation in the schema. The description adds minimal semantics by mentioning 'Contact ID' for 'id' and format options for 'response_format', but doesn't provide additional context beyond what's already in the schema descriptions (e.g., ID format specifics).

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: 'Get a single contact by ID' specifies the verb ('Get') and resource ('contact'), distinguishing it from list operations like 'itglue_list_contacts'. However, it doesn't explicitly differentiate from other get operations (e.g., 'itglue_get_organization'), which slightly reduces clarity.

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

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

The description implies usage by specifying 'by ID', suggesting it's for retrieving a specific contact rather than listing all contacts. However, it lacks explicit guidance on when to use this versus alternatives like 'itglue_list_contacts' or other get tools, and doesn't mention prerequisites or error cases.

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 strong behavioral hints (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description's burden is lower. It adds value by mentioning the return content ('Domain details including registrar and expiration') and the optional 'include' parameter for related credentials, which provides useful context beyond annotations. However, it does not disclose rate limits, authentication needs, or error behaviors.

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 efficiently structured with a clear purpose statement followed by bullet-point-like sections for 'Args' and 'Returns'. Every sentence adds value without redundancy, and it is front-loaded with the core functionality. The formatting enhances readability while keeping the content compact.

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 (3 parameters, 100% schema coverage, no output schema but annotations provide safety context), the description is largely complete. It covers purpose, parameters, and return content adequately. However, it could benefit from more explicit usage guidelines compared to siblings and additional behavioral details like error handling or authentication requirements to reach full completeness.

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

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

Schema description coverage is 100%, with clear documentation for all parameters in the input schema. The description adds minimal semantic value beyond the schema: it clarifies that 'include' can fetch 'passwords for related credentials' and notes the return format options, but these details are largely redundant with the schema's descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('a single domain by ID'), distinguishing it from sibling tools like 'itglue_list_domains' (which lists multiple domains) and other 'get_' tools for different resource types. It precisely defines the scope as retrieving one domain rather than a collection.

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 implies usage context by specifying 'by ID', suggesting this tool is for retrieving known domain records rather than searching or listing. However, it does not explicitly state when to use alternatives like 'itglue_list_domains' for browsing or other 'get_' tools for different resources, leaving some guidance implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds minimal behavioral context beyond this, mentioning the return includes 'all trait values' but not details like error handling, rate limits, or authentication needs. It does not contradict annotations.

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

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

The description is front-loaded with the core purpose, followed by brief parameter and return notes. It avoids redundancy, but the 'Args' and 'Returns' sections could be more integrated into a single narrative flow. Overall, it is efficient with minimal waste.

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 low complexity (simple retrieval), rich annotations, and 100% schema coverage, the description is mostly complete. It lacks an output schema but describes the return content. However, it could better address sibling tool differentiation and provide more behavioral context to fully compensate for the missing output schema.

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

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

Schema description coverage is 100%, with clear descriptions for all parameters (id, include, response_format). The description adds no additional semantic details beyond what the schema provides, such as examples or usage tips for 'include' or 'response_format'. Baseline 3 is appropriate given the schema's completeness.

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

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

The description clearly states the verb 'Get' and resource 'a single flexible asset by ID', distinguishing it from sibling tools like 'itglue_list_flexible_assets' (which retrieves multiple) and 'itglue_create_flexible_asset' (which creates). It specifies the singular nature and ID requirement, making the purpose unambiguous.

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

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

The description implies usage when needing a specific flexible asset by ID, but does not explicitly state when to use this versus alternatives like 'itglue_list_flexible_assets' for multiple assets or 'itglue_get_flexible_asset_type' for asset types. No exclusions or prerequisites are mentioned, leaving some ambiguity.

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 cover key behavioral traits (read-only, non-destructive, idempotent, open-world). The description adds value by explaining the optional 'include' parameter for field definitions and the 'response_format' choice, which provides context beyond annotations. However, it doesn't mention rate limits, authentication needs, or error handling, leaving some behavioral aspects uncovered.

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

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

The description is front-loaded with the core purpose, followed by a structured Args section and Returns statement. Every sentence earns its place with no redundancy. It's appropriately sized for a simple retrieval tool, making it easy to scan and understand quickly.

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 low complexity (simple GET operation), rich annotations, and full schema coverage, the description is mostly complete. It explains the optional inclusions and output format, which are key for usage. However, without an output schema, it could benefit from more detail on return values (e.g., structure of 'details'), but the annotations provide safety context, making it sufficient overall.

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

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

Schema description coverage is 100%, so the schema fully documents parameters. The description adds minimal semantics by briefly explaining 'include' and 'response_format' in the Args section, but this mostly repeats schema info. No additional syntax or format details are provided beyond what the schema offers, 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 verb 'Get' and the resource 'a single flexible asset type by ID', which is specific and distinguishes it from sibling tools like 'itglue_list_flexible_asset_types' (which lists multiple) and 'itglue_get_flexible_asset' (which gets a different resource). The purpose is unambiguous and well-defined.

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 implies usage context by specifying it's for retrieving a single item by ID, which differentiates it from list operations. However, it doesn't explicitly state when NOT to use it or name specific alternatives (e.g., 'use itglue_list_flexible_asset_types for multiple types'). The guidance is clear but lacks explicit exclusions.

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 key behavioral hints (read-only, open-world, idempotent, non-destructive), so the description adds minimal value beyond stating it returns 'Location details including full address'. It does not disclose additional traits like rate limits, authentication needs, or error handling, but 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?

The description is front-loaded with the core purpose, followed by a structured Args and Returns section. Every sentence is necessary and contributes to understanding, with no wasted words 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?

Given the simple tool (2 parameters, 100% schema coverage, rich annotations) and no output schema, the description is reasonably complete. It specifies the return content ('Location details including full address') and parameter usage, though it could mention format details for the output (e.g., structure of details).

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 clear descriptions for both parameters (e.g., 'id' as 'The unique ID of the resource', 'response_format' with enum and default). The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the specific action ('Get a single location by ID') and resource ('Location'), distinguishing it from sibling tools like 'itglue_list_locations' (which retrieves multiple locations) and 'itglue_create_location' (which creates rather than retrieves). The verb 'Get' is precise 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 implies usage context by specifying 'by ID', suggesting it should be used when you have a specific location identifier. It does not explicitly state when not to use it or name alternatives, but the context is clear enough to differentiate from list operations.

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, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond annotations by detailing the return content ('detailed information including name, type, status, quick notes, alerts, and links') and the IT Glue URL, which helps the agent understand the output structure and available 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?

The description is well-structured and front-loaded with the core purpose in the first sentence, followed by return details and parameter explanations. Every sentence adds value without redundancy, and the formatting with clear sections (Args, Returns) enhances readability efficiently.

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 low complexity (simple retrieval), rich annotations (covering read-only, non-destructive, open-world, idempotent), and 100% schema coverage, the description is complete. It explains what the tool does, what it returns, and parameter usage, making it sufficient for an agent to invoke correctly without needing an output schema.

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

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

Schema description coverage is 100%, with clear descriptions for both parameters (e.g., 'id' as 'The unique ID of the resource' and 'response_format' with enum values). The description adds minimal semantics beyond the schema, only restating that 'id' is required and listing the enum options without new insights, meeting the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Get a single organization by ID') and resource ('organization'), distinguishing it from sibling tools like 'itglue_list_organizations' (which lists multiple) and 'itglue_create_organization' (which creates new ones). The verb 'Get' precisely indicates retrieval rather than modification.

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 implies usage context by specifying 'by ID' and listing sibling tools like 'itglue_list_organizations', suggesting this tool is for retrieving a specific known organization rather than browsing. However, it lacks explicit guidance on when to use alternatives (e.g., 'itglue_list_organizations' for unknown IDs) or prerequisites like authentication.

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 this is a safe, read-only, idempotent operation (readOnlyHint: true, destructiveHint: false, idempotentHint: true). The description adds valuable context beyond this: it discloses the 'Password Access' permission requirement for viewing passwords, which is critical behavioral information not covered by annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by a critical note and parameter/return details. It's concise with no wasted sentences, though the 'Args' and 'Returns' sections could be integrated more smoothly into the flow.

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 moderate complexity (retrieval with permission constraints), rich annotations, and 100% schema coverage, the description is mostly complete. It covers purpose, permission requirements, parameters, and returns. However, without an output schema, it could benefit from more detail on the return structure (e.g., what fields beyond username/URL/password are included).

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%, providing full documentation of all parameters. The description adds minimal value beyond the schema: it mentions the 'show_password' parameter's effect ('include the actual password value') and the 'response_format' options, but these are already detailed in the schema descriptions. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the specific action ('Get a single password by ID') and resource ('password'), distinguishing it from sibling tools like 'itglue_list_passwords' (which lists multiple) and 'itglue_create_password' (which creates). The optional inclusion of the password value adds further specificity.

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 for usage: it's for retrieving a single password by ID, with an explicit note about the 'Password Access' permission requirement. However, it doesn't explicitly state when to use this versus alternatives like 'itglue_list_passwords' for browsing or 'itglue_check_password_access' for permission verification.

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, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds value by specifying that filtering is optional and listing returns paginated results (implied via page/page_size), which are useful behavioral details beyond annotations. 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 well-structured with a clear opening sentence, explanatory paragraph, and bullet-pointed args/returns. It is appropriately sized for a tool with many parameters, though the args section is somewhat redundant given the schema. Every sentence adds value, but the bullet points could be 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?

Given the tool's complexity (16 parameters, no output schema), the description is mostly complete: it explains the purpose, provides usage context, and lists parameters. However, it lacks details on return values beyond 'List of configurations with details,' which could be more specific given no output schema. Annotations cover safety well, but more behavioral context (e.g., pagination limits) would help.

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 fully documents all 16 parameters. The description lists parameters with brief notes (e.g., 'partial match' for name, 'default' values), but these mostly repeat or summarize schema info without adding significant new semantics. 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 clearly states the verb ('List') and resource ('configurations (devices/assets) in IT Glue'), and distinguishes this tool from siblings like 'itglue_get_configuration' (singular retrieval) and 'itglue_create_configuration' (creation). It also explains what configurations represent (IT assets like servers, workstations, etc.), adding domain context.

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 for usage ('with optional filtering') and implies when to use it (for listing configurations vs. getting a single one or creating/updating). However, it does not explicitly state when NOT to use it or name specific alternatives among siblings, though the sibling list suggests alternatives like 'itglue_get_configuration' for single items.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds useful behavioral context beyond annotations: it explains what contacts represent ('people associated with organizations - employees, vendors, or other important individuals'), mentions pagination behavior through the Args section, and specifies the return format options ('markdown' or 'json'). This provides valuable operational context that annotations don't cover.

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

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

The description is well-structured with a clear purpose statement upfront, followed by explanatory context about contacts, then parameter details, and finally return information. It's appropriately sized for an 11-parameter tool. The only minor inefficiency is the Args section duplicating schema information, but overall it's front-loaded and each section earns its place by providing useful context.

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 (11 parameters, no output schema), the description provides good contextual completeness. It explains what contacts are, documents all parameters (albeit redundantly), specifies return format options, and describes what the tool returns ('List of contacts with names, titles, and contact information'). The annotations cover safety aspects well. The main gap is lack of explicit differentiation from sibling tools, but overall this is quite complete for a list operation.

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

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

Schema description coverage is 100%, meaning all parameters are well-documented in the schema. The description's Args section repeats parameter information (e.g., 'page (number): Page number (default: 1)') that's already in the schema, adding minimal value. However, it does provide a high-level summary of filtering capabilities ('with optional filtering') and mentions the response_format parameter specifically, which offers some semantic context. Given the comprehensive schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'List contacts in IT Glue with optional filtering' and explains that contacts represent people associated with organizations. This provides a specific verb ('List') and resource ('contacts in IT Glue'). However, it doesn't explicitly differentiate from sibling tools like 'itglue_get_contact' (singular) or 'itglue_create_contact', missing an opportunity to clarify when to use this list tool versus those alternatives.

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 implies usage through the phrase 'with optional filtering' and the explanation of what contacts represent, suggesting this is for retrieving multiple contacts. However, it lacks explicit guidance on when to use this tool versus alternatives like 'itglue_get_contact' (for a single contact) or 'itglue_create_contact'. There's no mention of prerequisites or when-not-to-use scenarios, leaving usage context somewhat vague.

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 this is a read-only, non-destructive, idempotent, and open-world operation. The description adds valuable context beyond annotations: it explains what domains track ('domain registrations and their expiration dates'), mentions optional filtering, and specifies the return content ('List of domains with registrar and expiration info'). This enhances behavioral understanding without contradicting annotations, though it doesn't cover aspects like rate limits or authentication needs.

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

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

The description is well-structured and appropriately sized: it starts with a clear purpose statement, adds context in a second sentence, then details parameters and returns in separate sections. Every sentence earns its place by providing useful information. However, the 'Args' section is somewhat redundant given the schema's 100% coverage, slightly reducing efficiency, but the overall flow is logical and 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 tool's complexity (8 parameters, no output schema) and rich annotations, the description is fairly complete. It covers purpose, domain context, parameters, and return values. The lack of an output schema is mitigated by the description specifying return content. However, it could be more comprehensive by explaining pagination behavior or error handling, but for a list tool with good annotations, this is 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%, meaning all parameters are well-documented in the schema. The description lists parameters in an 'Args' section, but this mostly repeats schema information (e.g., 'page (number): Page number (default: 1)') without adding significant semantic value. It does clarify that 'include' can fetch 'passwords for related credentials,' which slightly expands on the schema's enum, but overall, the description doesn't compensate beyond the schema's thorough documentation.

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

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

The description clearly states the tool's purpose: 'List domains in IT Glue with optional filtering.' It specifies the verb ('List') and resource ('domains in IT Glue'), and the second sentence adds context about what domains track. However, it doesn't explicitly differentiate from sibling tools like 'itglue_get_domain' (singular) or 'itglue_list_expirations', which might overlap in functionality, preventing a perfect score.

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

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

The description implies usage through the phrase 'with optional filtering,' suggesting it's for retrieving multiple domains with customization. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'itglue_get_domain' (for a single domain) or 'itglue_list_expirations' (which might list domains based on expiration dates). No exclusions or prerequisites are mentioned, leaving usage context partially inferred.

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, openWorldHint=true, and idempotentHint=true, covering the safety profile. The description adds useful context about what types of items are tracked and the pagination behavior, but doesn't provide additional behavioral details like rate limits, authentication requirements, or error conditions beyond what annotations provide.

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

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

The description is well-structured with a clear purpose statement, usage context, parameter summary, and return information. However, the Args section is somewhat redundant given the comprehensive schema documentation. The description could be more concise by focusing only on value-added information beyond the schema.

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 listing tool with comprehensive annotations and 100% schema coverage, the description provides adequate context. It explains the tool's purpose, gives usage examples, summarizes parameters, and describes the return format. The main gap is the lack of output schema, but the description compensates by stating the return format options and what's returned.

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 input schema already documents all 8 parameters thoroughly with descriptions, enums, defaults, and constraints. The description's Args section mostly repeats schema information, adding minimal value. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the verb ('List') and resource ('upcoming expirations across all resource types'), providing specific examples of what types of items are tracked (warranties, SSL certificates, domain renewals). It distinguishes itself from sibling tools by focusing on expiration tracking rather than general listing or CRUD operations on specific resource types.

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 about when to use this tool ('Useful for tracking warranties, SSL certificates, domain renewals, and other time-sensitive items'), but doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools. The context is helpful but lacks explicit exclusion 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 strong behavioral hints (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the bar is lower. The description adds useful context about the tool's purpose in understanding fields for creation/update operations, but it doesn't disclose additional behavioral traits like rate limits, authentication needs, or pagination behavior. No contradiction with annotations exists.

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

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

The description is well-structured and front-loaded with the core purpose in the first sentence. The second sentence adds practical utility context, and the 'Args' and 'Returns' sections are clear and efficient. Every sentence earns its place with no redundant 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 tool's low complexity (2 parameters, 100% schema coverage, no output schema), the description is mostly complete. It explains the purpose, usage context, parameters, and return value. However, it could be slightly more complete by mentioning the lack of pagination or filtering options, or providing a brief example of the output structure since there's no output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters (flexible_asset_type_id and response_format). The description adds minimal value beyond the schema by mentioning the parameters in the 'Args' section and clarifying the return format options, but it doesn't provide additional semantic context like examples or edge cases. Baseline 3 is appropriate when 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 clearly states the specific action ('List all fields') and resource ('for a specific flexible asset type'), distinguishing it from sibling tools like 'itglue_list_flexible_asset_types' (which lists types, not fields) and 'itglue_get_flexible_asset' (which retrieves asset instances). The second sentence further clarifies the purpose by explaining its utility for understanding traits when creating/updating assets.

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 for when to use this tool ('to understand what traits are available when creating or updating flexible assets'), but it does not explicitly state when NOT to use it or name specific alternatives. For example, it doesn't contrast with 'itglue_get_flexible_asset_type' which might provide related metadata.

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 strong behavioral hints (readOnly, openWorld, idempotent, non-destructive). The description adds valuable context beyond annotations: it explains what flexible assets are with concrete examples, mentions pagination behavior through the 'page' and 'page_size' parameters, and describes the return format options. This provides useful operational context that annotations don't cover.

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

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

The description is well-structured with a clear purpose statement upfront, followed by explanatory context about flexible assets, then a parameter summary, and finally return information. It's appropriately sized for a tool with 10 parameters. Minor improvements could include better integration of the parameter information rather than a separate 'Args' section that duplicates 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 tool's complexity (10 parameters, no output schema), the description provides good contextual completeness. It explains what flexible assets are, covers the main filtering capabilities, mentions pagination, and describes return format options. The annotations provide excellent behavioral coverage. The main gap is lack of explicit sibling tool differentiation, but overall it's quite complete for a list operation.

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

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

With 100% schema description coverage, the input schema already documents all 10 parameters thoroughly. The description's 'Args' section mostly repeats what's in the schema, adding minimal additional semantic context. It does add the note that flexible_asset_type_id is 'recommended' for trait filtering, which provides some guidance. The baseline of 3 is appropriate when schema coverage 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 the tool's purpose: 'List flexible assets in IT Glue with optional filtering.' It specifies the verb ('List') and resource ('flexible assets'), and provides examples of what flexible assets are. However, it doesn't explicitly differentiate from sibling tools like 'itglue_get_flexible_asset' (singular) or 'itglue_list_flexible_asset_types', which would be needed for a score of 5.

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 implied usage context by mentioning 'optional filtering' and examples of flexible assets, but lacks explicit guidance on when to use this tool versus alternatives. It doesn't mention when to use this list tool versus 'itglue_get_flexible_asset' for single assets or 'itglue_list_flexible_asset_types' for types, nor does it specify prerequisites or exclusions.

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, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds useful context about pagination behavior and filtering capabilities, but doesn't disclose rate limits, authentication needs, or error conditions. With annotations providing core behavioral traits, the description adds moderate value.

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

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

The description is well-structured with purpose, usage context, parameters, and return value in separate sections. It's appropriately sized with no redundant information. However, the 'Args' section could be more integrated with the flow rather than a separate list, and some sentences 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?

For a read-only listing tool with comprehensive annotations and schema coverage, the description is mostly complete. It explains the purpose, usage context, parameters, and return value. The main gap is the lack of output schema, but the description compensates by describing the return format. It could benefit from more detail on pagination behavior or error cases.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description mentions parameters briefly in the 'Args' section but doesn't add significant meaning beyond what's in the schema (e.g., it doesn't explain filtering logic or 'include' implications). Baseline 3 is appropriate when 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 clearly states the verb ('List') and resource ('all flexible asset types defined in IT Glue'), making the purpose specific and unambiguous. It distinguishes from siblings like 'itglue_get_flexible_asset_type' (singular) and 'itglue_list_flexible_assets' (assets vs. asset types), providing clear differentiation.

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

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

The description explicitly states when to use this tool: 'Use this to find the type ID needed when creating or filtering flexible assets.' This provides clear context for its purpose. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among siblings, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context about pagination behavior ('page', 'page_size') and output format options ('markdown' or 'json'), which are not captured in annotations. No contradiction with annotations exists.

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

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

The description is well-structured with a clear opening sentence, explanatory context, and a parameter list. However, the Args section duplicates schema information unnecessarily, and the Returns statement could be more informative. It's mostly efficient but has some 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?

For a read-only list tool with rich annotations and full schema coverage, the description provides adequate context: it explains the resource, mentions optional filtering, and notes output format. Without an output schema, the Returns statement is brief but acceptable. It covers the essentials but could better address sibling tool differentiation.

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 fully documents all 11 parameters. The description lists 9 parameters in its Args section (missing 'psa_id' and 'sort_direction'), adding minimal value beyond the schema. It does clarify that filtering is 'optional', which is helpful but not substantial. Baseline 3 is appropriate given the comprehensive schema.

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

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

The description clearly states the verb ('List') and resource ('locations in IT Glue'), specifies the domain context ('physical addresses associated with organizations'), and distinguishes from siblings like 'itglue_get_location' (single location) and 'itglue_create_location' (write operation). The purpose is specific and well-differentiated.

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 implies usage for listing locations with filtering, but doesn't explicitly state when to use this tool versus alternatives like 'itglue_get_location' (for single location) or 'itglue_list_organizations' (for related data). No explicit when-not-to-use guidance or prerequisites are provided, leaving usage context somewhat implied.

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, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond this: it explains what organizations represent (client companies with specific data types), mentions partial match filtering for 'name', and describes the return format options ('markdown' or 'json'). No contradiction with annotations exists.

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

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

The description is well-structured with a clear opening sentence, followed by explanatory context, a parameter list, and return information. It is appropriately sized for a tool with 9 parameters, though the parameter details largely repeat schema information, making some content redundant rather than strictly necessary.

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, no output schema), the description is mostly complete: it explains the tool's purpose, provides usage context, details parameters and returns, and adds behavioral insights. However, it lacks explicit guidance on pagination behavior (e.g., total pages or item counts) and does not fully differentiate from all sibling tools, leaving minor 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 description coverage is 100%, providing detailed parameter documentation. The description adds minimal semantic value beyond the schema: it restates default values and max constraints for 'page' and 'page_size', and clarifies that 'name' filtering uses partial match (already in schema). With high schema coverage, the baseline is 3, and the description does not significantly enhance parameter understanding.

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

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

The description clearly states the action ('List organizations in IT Glue') and resource ('organizations'), with additional context that 'Organizations represent client companies in IT Glue' and contain various data types. This distinguishes it from sibling tools like 'itglue_get_organization' (singular retrieval) and 'itglue_create_organization' (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?

The description provides clear context for when to use this tool: for listing organizations with optional filtering and pagination. It implies usage for bulk retrieval rather than single-item lookups (like 'itglue_get_organization'), but does not explicitly state when NOT to use it or name specific alternatives among siblings.

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 this as read-only, non-destructive, idempotent, and open-world, which covers basic safety. The description adds valuable behavioral context beyond annotations: it discloses the authentication requirement ('Password Access' permission with 403 error consequence), clarifies the default behavior for password values (excluded unless show_password=true), and mentions the return format options. This provides practical implementation guidance that annotations alone don't convey.

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

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

The description is well-structured with clear sections (purpose statement, important note, Args, Returns). It's appropriately sized for an 11-parameter tool with important behavioral notes. The front-loaded purpose statement is clear, though the Args section could be more concise given the comprehensive schema coverage.

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 (11 parameters, authentication requirements, filtering options) and the absence of an output schema, the description provides excellent contextual completeness. It covers the purpose, authentication prerequisites, parameter overview, return behavior, and format options. The combination of rich annotations and this descriptive text gives the agent everything needed to use the tool 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 description coverage is 100%, so the schema already fully documents all 11 parameters. The description's Args section repeats parameter information without adding significant semantic value beyond what's in the schema. However, it does provide a helpful summary of the filtering capabilities ('optional filtering') and clarifies the show_password behavior in the Returns note, which offers some contextual framing.

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 ('List') and resource ('passwords in IT Glue'), making the purpose immediately apparent. It distinguishes this tool from sibling tools like 'itglue_get_password' (singular retrieval) and 'itglue_create_password' (creation), establishing its role as a filtered listing operation.

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 about when to use this tool (for listing passwords with filtering) and includes an important prerequisite about 'Password Access' permission. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools (e.g., 'itglue_get_password' for single password retrieval).

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 cover key behavioral traits (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), but the description adds useful context: it specifies the return value ('The updated configuration') and mentions the 'response_format' parameter for output control. This enhances transparency beyond annotations, though it doesn't detail side effects like rate limits or authentication needs.

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

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

The description is well-structured with a brief purpose statement followed by an 'Args' list and return note. It's appropriately sized for a tool with many parameters, though the 'Args' section is somewhat redundant with the schema. Every sentence adds value, but it could be more front-loaded with key usage 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 tool's complexity (14 parameters, mutation operation) and rich annotations, the description is adequate but has gaps. It lacks output schema, so the return value description ('The updated configuration') is minimal. It doesn't explain error cases, prerequisites, or how it interacts with siblings, leaving the agent to rely on annotations and schema for full context.

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

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

Schema description coverage is 100%, so the schema fully documents all 14 parameters. The description lists parameters in the 'Args' section but adds minimal semantic value beyond the schema (e.g., it repeats 'Configuration ID (required)' similar to schema's 'unique ID'). No additional context like default behaviors or interdependencies is provided, 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 verb ('Update') and resource ('existing configuration in IT Glue'), making the purpose specific and understandable. It distinguishes from sibling tools like 'itglue_create_configuration' by specifying 'existing', but doesn't explicitly contrast with other update tools (e.g., itglue_update_contact).

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing configuration ID), when not to use it, or how it differs from other update tools in the sibling list. The agent must infer usage from the tool name alone.

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

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

Annotations provide key behavioral hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description doesn't need to repeat these. It adds some context by noting that contact_emails and contact_phones arrays 'replace existing' data, which clarifies mutation behavior beyond annotations. However, it lacks details on permissions, rate limits, or error handling.

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

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

The description is well-structured with a clear opening sentence followed by an 'Args' section. It's appropriately sized for a tool with 12 parameters, though the 'Args' list is somewhat redundant given the schema. Every sentence adds value, and it's front-loaded with the core 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?

For a mutation tool with 12 parameters and no output schema, the description is adequate but has gaps. Annotations cover safety and idempotency, and the schema documents inputs well. However, the description doesn't explain the return value beyond 'The updated contact' (no format details), and it lacks context on error cases or dependencies, leaving some ambiguity for the agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description lists parameters but adds minimal extra meaning beyond the schema (e.g., noting 'replaces existing' for arrays, which is also in the schema). It doesn't explain parameter interactions or provide examples, staying at the baseline for high schema coverage.

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

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

The description clearly states the verb ('Update') and resource ('existing contact in IT Glue'), making the purpose immediately understandable. It distinguishes from siblings like 'itglue_create_contact' by specifying it's for existing contacts, though it doesn't explicitly contrast with other update tools like 'itglue_update_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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the contact ID), when to use 'itglue_create_contact' instead, or how it differs from other update tools in the sibling list. The agent must infer usage from the name and description alone.

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 key behavioral hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description doesn't need to repeat these. However, it adds minimal context beyond annotations—it mentions the tool updates an existing asset and specifies the return format options, but doesn't describe potential side effects, rate limits, or authentication requirements. The description doesn't contradict annotations, as 'Update' aligns with readOnlyHint=false.

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

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

The description is well-structured and appropriately sized, with a clear opening sentence followed by an Args section. It avoids unnecessary fluff, though the Args section could be more concise by relying on the schema. Every sentence serves a purpose, but the parameter listing is somewhat redundant given the schema coverage.

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 (5 parameters, nested objects, no output schema) and rich annotations, the description is adequate but has gaps. It covers the basic purpose and parameters but lacks usage guidelines, detailed behavioral context (e.g., what 'traits' updates entail), and output specifics. With no output schema, the description should ideally explain the return value more thoroughly, though it does mention the format options.

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 fully documents all parameters. The description lists parameters in the Args section but adds no additional meaning beyond what's in the schema (e.g., it repeats that 'id' is required and 'response_format' has enum values). Since the schema does the heavy lifting, the baseline score of 3 is appropriate, with no extra value added.

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 ('Update') and resource ('existing flexible asset in IT Glue'), making the purpose unambiguous. It distinguishes from sibling tools like 'itglue_create_flexible_asset' by specifying it updates existing assets rather than creating new ones. However, it doesn't explicitly differentiate from other update tools (e.g., itglue_update_configuration) beyond the resource type.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing flexible asset ID), when to use it over other update tools for different resources, or any specific scenarios where this tool is appropriate. The only implied usage is updating flexible assets, but no explicit context is given.

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 cover key behavioral traits (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the description doesn't need to repeat these. It adds minimal context by specifying it updates an 'existing' location and mentions the return value, but doesn't elaborate on side effects, permissions, or error conditions beyond what annotations imply.

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

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

The description is appropriately sized and front-loaded with the core purpose. The parameter listing is somewhat redundant given the schema, but it's organized clearly. The return statement is concise. Overall, it's efficient with minimal fluff.

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 (14 parameters, mutation operation) and rich annotations, the description is adequate but lacks depth. It doesn't explain output details (no output schema provided), error handling, or integration with sibling tools. It meets minimum requirements but doesn't fully compensate for the absence of an output schema.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description lists parameters but adds no meaningful semantics beyond the schema (e.g., it doesn't explain relationships between fields like region_id and country_id). With high schema coverage, the baseline is 3, and the description doesn't significantly enhance understanding.

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

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

The description clearly states the action ('Update') and resource ('existing location in IT Glue'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'itglue_create_location' by specifying it's for updates, though it doesn't explicitly differentiate from other update tools like 'itglue_update_contact'.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing location ID), when not to use it, or how it compares to similar update tools for other resources like contacts or organizations in the sibling list.

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

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

The description adds valuable context beyond annotations: it specifies that 'alert' can be set to null to clear an alert, and it documents the return value ('Returns: The updated organization'). Annotations already cover safety (readOnlyHint=false, destructiveHint=false) and idempotency, but the description provides practical behavioral details that enhance understanding.

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

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

The description is well-structured with a clear purpose statement followed by an 'Args' section and a 'Returns' statement. It's appropriately sized for a 9-parameter tool, though the parameter listing could be more concise since schema coverage is complete. 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 tool's complexity (9 parameters, mutation operation) and lack of output schema, the description does a good job: it explains the purpose, lists parameters with notes, specifies the return value, and adds behavioral context. With annotations covering safety and idempotency, the description provides sufficient context for effective use, though it could benefit from more usage guidance.

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 fully documents all parameters. The description lists parameters with brief notes but doesn't add significant meaning beyond what's in the schema (e.g., it repeats 'Organization name' for 'name'). It provides a baseline level of information without extra insights.

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 specific action ('Update an existing organization') and resource ('in IT Glue'), distinguishing it from sibling tools like 'itglue_create_organization' and 'itglue_get_organization'. It precisely communicates the tool's function without ambiguity.

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

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

The description implies usage for updating existing organizations but doesn't explicitly state when to use this tool versus alternatives like 'itglue_create_organization' or 'itglue_get_organization'. No guidance is provided on prerequisites, error conditions, or specific use-case scenarios beyond the basic function.

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 this is a mutable (readOnlyHint: false), idempotent, non-destructive operation. The description adds minimal behavioral context beyond this - it mentions the return value format but doesn't explain what happens with partial updates, validation rules, or permission requirements. With good annotation coverage, the description provides some but not rich additional behavioral insight.

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

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

The description is efficiently structured with a clear purpose statement followed by parameter listing and return information. However, the parameter list is somewhat redundant given the comprehensive schema, and the 'Args:' section could be more concise or integrated better with the main description.

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 mutation tool with 10 parameters, good annotations, and no output schema, the description provides basic context but lacks depth. It doesn't explain update semantics (partial vs full updates), error handling, permission requirements, or how this tool relates to sibling operations. The return format is mentioned, but without an output schema, more detail on response structure would be helpful.

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 all parameters are documented in the schema. The description lists parameters but doesn't add meaningful semantic context beyond what's already in the schema descriptions (e.g., explaining relationships between fields, update semantics, or special constraints). The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Update') and resource ('an existing password entry in IT Glue'), distinguishing it from sibling tools like 'itglue_create_password' (create) and 'itglue_get_password' (read). It specifies the exact type of resource being modified.

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?

No guidance is provided on when to use this tool versus alternatives like 'itglue_create_password' or 'itglue_get_password'. The description doesn't mention prerequisites, error conditions, or typical use cases for updating versus creating new entries.

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