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

Annotations indicate this is a write operation (readOnlyHint=false) and not idempotent. The description adds behavioral context: max file size of 25 MB, explanation of how file_name is inferred, and the constraint that file_path works only with stdio transport. No contradictions with annotations.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Each sentence provides necessary information without redundancy. It efficiently covers key constraints and usage notes.

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 7 parameters, 2 required, and no output schema, the description covers usage well but lacks information about the return value or error states. It does not explain what happens on a successful attachment (e.g., response format) or how to handle failures. The schema and annotations partially compensate, but some context is missing.

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 description adds significant meaning: it clarifies that exactly one image source must be provided, explains that content_base64 can include a data URI prefix, that the server fetches and encodes the url, and that file_name extension is important for type detection. This goes well beyond the schema descriptions.

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

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

The description uses a specific verb ('attach') and resource ('record'), lists example record types (documents, flexible assets, etc.), and distinguishes from sibling tools like itglue_create_document by clearly stating it adds attachments to existing records.

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

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

The description provides explicit guidance on how to use the tool: specify exactly one image source among content_base64, url, or file_path, and provide a file name with extension. It also notes that file_name can be inferred and that file_path is for stdio only. However, it does not explicitly state when not to use this tool versus alternatives like listing or deleting attachments.

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 write operation (readOnlyHint=false). The description adds that the document is created as a draft, implying it is not visible until published. This provides useful behavioral context beyond annotations, and there is no contradiction.

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

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

Two concise sentences with no fluff. The first sentence states the action and state, the second supplies next steps. Every word earns its place.

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

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

Given the tool's role as the first step in a multi-step creation process, the description covers the essentials: what it does, required parameters, and follow-up tools. No output schema exists, so return value details are not expected. The workflow reference to sibling tools adds 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%, so the schema already documents all four parameters. The description adds minimal additional meaning (e.g., 'in an organization' for organization_id). Baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states 'Create a new document as a DRAFT in an organization.' This is a specific verb (create) and resource (document) with a defined state (draft). It distinguishes from siblings like itglue_create_document_section (adds content) and itglue_publish_document (makes visible).

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 a workflow: create draft, then add content with itglue_create_document_section, then publish with itglue_publish_document. This gives clear context on when to use this tool and what steps follow. However, it does not explicitly state when not to use it.

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

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

Annotations indicate this is a write operation with possible side effects (openWorldHint true) but not destructive. The description adds value by disclosing the behavior of inline images in HTML (rendering depends on IT Glue's sanitization) and explicitly distinguishing between inline images and attached files. There is 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 concise, with three sentences covering purpose, type details, and a caveat. It is front-loaded and efficiently communicates essential information without redundancy.

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

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

Given no output schema, the description adequately covers input behavior and special conditions. It could be improved by briefly mentioning what the return value contains (e.g., the created section object), but the context is largely complete for a creation tool.

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

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

Schema coverage is 100% with descriptions for all 7 parameters. The description enriches meaning by explaining how parameters relate to section types (e.g., level required for Heading, duration for Step, content semantics vary by type).

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 'Add a section to a document' and specifies four types with distinct behaviors. It also differentiates from the sibling tool itglue_create_attachment by explicitly noting that to attach image files, use that tool.

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

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

The description provides explicit when-to-use guidance by detailing section types and their required/optional parameters. It also tells when not to use (for attaching image files) and suggests the alternative sibling tool.

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

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

The description discloses that the tool creates a flexible asset and that required traits must be provided. It adds the naming convention for traits (lowercased, hyphenated). Annotations already indicate it is not readonly and not destructive, and the description is consistent. No contradictions.

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

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

The description is only two sentences, each with essential information. No redundant words. The structure front-loads the core purpose and then explains the key parameter detail.

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 (nested object for traits, 4 parameters) and no output schema, the description covers the critical aspect of how to construct traits. It points to another tool for more detail. It could mention the response format parameter, but that already has a default and enum in the 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 coverage is 100%, so parameters are already described. The description adds value by specifying that trait keys should use lowercased, hyphenated names and by referencing a sibling tool to inspect available traits. This clarifies the nested parameter beyond the schema.

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

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

The description clearly states 'Create a flexible asset' with a specific verb and resource. It distinguishes from sibling tools like itglue_update_flexible_asset (update) and itglue_list_flexible_assets (list), 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 guidance on how to format the 'traits' parameter (lowercased, hyphenated names) and instructs to inspect traits using itglue_get_flexible_asset_type. It implies that all required traits must be provided, which helps correct usage, though it does not explicitly state when not to use the tool or list alternatives.

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

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

The description emphasizes permanence ('PERMANENTLY delete' and 'cannot be undone'), which aligns with and adds context beyond the destructiveHint annotation. It does not cover authorization or rate limits, but annotations already handle the destructive nature.

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

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

Two sentences, front-loaded with the key fact of permanence. Every sentence provides essential information without redundancy.

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

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

For a destructive operation with three parameters and no output schema, the description fully covers the purpose, the key usage tip (how to get the ID), and the impact (permanent). No additional details are necessary.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds slight value by connecting attachment_id to itglue_list_attachments, but otherwise does not provide new information beyond the schema.

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

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

The description clearly states the action (delete) and the resource (attachment from a record). It also mentions that it is permanent, distinguishing it from sibling create tools.

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

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

It advises using itglue_list_attachments to find the attachment ID, providing a clear prerequisite. However, it does not explicitly state when to avoid using this tool or mention alternatives like itglue_delete_documents for similar 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 provide destructiveHint=true and readOnlyHint=false. The description adds value by stating 'PERMANENTLY delete' and that it includes all sections, which is beyond what annotations convey. No contradiction with annotations.

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

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

The description is a single sentence that is front-loaded with critical information ('PERMANENTLY delete') and contains no unnecessary words. Every element earns its place.

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

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

Given the simple delete operation and schema covering the only parameter, the description is largely complete. It covers the irreversible nature and scope. However, it omits any mention of return values or error behavior, which is a minor gap.

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

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

The input schema has one parameter with 100% description coverage. The tool description does not add any additional parameter semantics beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states it 'PERMANENTLY delete[s] one or more documents, including all their sections', specifying the action (delete), resource (documents), and scope (all sections). This distinguishes it from sibling tools like itglue_delete_document_section.

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 emphasizes irreversibility ('cannot be undone'), implying use only when certain. However, it does not explicitly contrast with alternatives like deleting individual sections or attachments, leaving the agent to infer when to choose this tool over siblings.

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

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

The description emphasizes 'PERMANENTLY delete' and 'cannot be undone', aligning with destructiveHint=true. It adds behavioral context about irreversibility beyond the annotation, which is helpful. No contradictions.

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

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

Two sentences, no unnecessary words. The key information (permanence, purpose) is front-loaded. Every sentence adds value.

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

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

For a simple delete operation with 2 required parameters and no output schema, the description explains the purpose and irreversibility. It does not cover error cases or dependencies, but is sufficient for typical usage.

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

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

The input schema already describes both parameters (document_id and section_id) with 100% coverage. The description does not add extra semantic meaning to the parameters beyond what the schema provides.

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 (delete a section), the resource (one section from a document), and the purpose (restructuring layout). It distinguishes from sibling tools like itglue_delete_documents or itglue_delete_attachment.

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 says 'Useful for restructuring a document's layout' which implies when to use, but does not explicitly exclude other use cases or contrast with alternatives like updating the section order. No 'when not to use' guidance is given.

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

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

Annotations already provide destructiveHint=true. Description adds 'PERMANENTLY' and 'cannot be undone', reinforcing the destructive nature but not adding new behavioral insight beyond annotations.

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

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

Single sentence, front-loaded with key information. No wasted words.

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

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

For a simple deletion tool with one param and no output schema, the description is fully adequate. It conveys the action and consequence.

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

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

Schema coverage is 100%, so description need not compensate. The description does not add meaning to the parameter beyond what's in the schema.

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

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

Clearly states the action (delete), resource (flexible asset), and emphasizes permanence. Distinguishes from siblings like update or get tools.

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

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

Implies caution with 'cannot be undone', but does not explicitly state when to use or when not to use this tool over alternatives. No comparison to other tools.

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

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

Annotations already indicate read-only, idempotent, etc. Description adds valuable context: section content is HTML, markdown converts to plain text, and response may be truncated. No contradictions.

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

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

Two sentences, concise and front-loaded with the primary purpose. Every sentence adds value with zero 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 an output schema exists (not shown but flagged true) and annotations cover safety, the description covers main purpose, format nuance, and truncation fallback. No major 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 covers 100% of parameters, so baseline is 3. Description adds minimal extra meaning beyond schema (noting markdown vs json), but is adequate.

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

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

Description clearly states verb 'Get', specific resource 'document by ID', and includes that it retrieves all sections with content, distinguishing it from sibling tools like itglue_get_document_section.

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

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

Provides explicit guidance on when to use the sibling tool (if response truncated), but does not cover other alternatives like itglue_list_documents or when to prefer this tool over other getters.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing that the content is HTML on the wire and that markdown output converts to plain text, providing transparency about the output format and potential data transformation.

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

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

The description is a single sentence that is efficient and front-loaded with the verb and resource. Every word serves a purpose, and there is no wasted text.

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

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

Given the presence of an output schema and comprehensive annotations, the description covers the essential aspects: purpose, scope, and format conversion. It is complete for a retrieval tool with read-only semantics.

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 baseline is 3. The description does not add extra meaning beyond the schema; it only mentions 'full content' which is already implied by the tool's purpose.

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', the resource 'one document section', and the scope 'full content'. It also mentions the format conversion from HTML to markdown/plain text, which distinguishes it from sibling tools like 'itglue_get_document' or 'itglue_list_document_sections'.

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 retrieving a single section's full content, but lacks explicit guidance on when to use this tool versus alternatives like 'itglue_list_document_sections' or when not to use it. No exclusion criteria are provided.

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, idempotentHint=true, destructiveHint=false, covering safety. The description adds only 'including all of its traits', which is implicit. No mention of error handling, rate limits, or authentication needs 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 a single clear sentence that front-loads the purpose. There is no waste; every word adds value.

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

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

Given the tool's simplicity (read by ID, two params), the presence of an output schema, and comprehensive annotations, the description is complete enough. It does not need to detail return format or error states.

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 both parameters. The description adds no parameter-specific meaning beyond 'by ID', which matches the required parameter. Baseline 3 is appropriate.

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

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

The description clearly states 'Get one flexible asset by ID, including all of its traits', using a specific verb and resource. It distinguishes from sibling tools like 'list_flexible_assets' (for listing) and other get tools by focusing on a single asset retrieval via ID.

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 (e.g., list_flexible_assets for multiple assets, update_flexible_asset for modifications). It lacks explicit context, exclusions, or mentions of prerequisites.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by specifying that the tool returns field definitions (name, kind, required) and explains their purpose as trait keys for create/update operations, going beyond annotation coverage.

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

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

The description is a single clear sentence that front-loads the key information. Slight penalty for not being more structured, but it is concise and effective.

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

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

Given the tool's simplicity and the presence of an output schema (as indicated in context signals), the description adequately covers what the tool does without needing to detail return values.

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 baseline is 3. The description does not add further meaning to the parameters beyond what the schema provides.

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 gets a flexible asset type by ID and includes field definitions. It distinguishes from sibling tools like itglue_list_flexible_asset_types (list vs get) and itglue_get_flexible_asset (asset vs 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 implies usage for retrieving field definitions needed to create or update assets, but lacks explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, making the tool's safe, read-only behavior clear. The description adds no further behavioral context (e.g., error handling, rate limits), but it is consistent and not contradictory.

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

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

The description is a single, front-loaded sentence with no waste. However, it omits potential useful details like output content, making it slightly under-informative for its brevity.

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

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

Given the output schema exists, the description need not explain return values. However, it does not mention the available output format options or provide any distinction from sibling tools beyond the basic purpose. Adequate for a simple get-by-id tool but lacks enrichment.

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

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

Schema coverage is 100% with both parameters already described. The description mentions 'by ID' relating to organization_id but adds no new meaning beyond the schema's existing description for that parameter. It does not address response_format.

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 states 'Get a single IT Glue organization by ID,' clearly specifying the verb ('Get'), resource ('IT Glue organization'), and mechanism ('by ID'). This implicitly distinguishes it from siblings like 'itglue_list_organizations' which retrieves multiple organizations.

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 (e.g., when to use itglue_list_organizations instead). There are no explicit when-to-use or when-not-to-use instructions.

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 readOnly, idempotent, and openWorld hints. Description adds specifics on returned fields, which is useful beyond annotations. No contradictions.

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

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

Single sentence, front-loaded with action and resource, no unnecessary words. Highly 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 that an output schema exists, the description covers the essential purpose and what the agent gets. It is complete for a read-only list tool with good annotations.

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

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

Schema has 100% coverage with descriptions for all 5 parameters. Description adds minimal extra parameter info; the mention of 'attachment IDs (needed for delete)' provides context for the return value but not parameters themselves.

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

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

Description clearly states the verb 'list', the resource 'attachments on a record', and lists the data returned (IDs, names, types, URLs). It distinguishes well from sibling tools like create or delete attachment.

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?

Implicitly suggests using this before deleting an attachment by noting that attachment IDs are 'needed for delete'. No explicit when-not or alternatives, but context is clear enough.

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 read-only, idempotent, non-destructive. The description adds that it returns only summary metadata (name, parent folder, document count) and explains filter matching and parent_id null meaning. This provides useful behavior beyond the structured fields.

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

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

The description is 4 sentences, front-loaded with purpose, then output summary, use case, and parameter details. Every sentence adds value without redundancy.

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

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

Given 7 parameters and a read-only list tool with pagination and output format, the description covers purpose, output, and key parameter behaviors. Sorting and response_format are documented in the schema; pagination details are not repeated but are in schema. The presence of an output schema reduces the need to describe return values.

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

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

Schema descriptions cover all parameters. The description adds extra context for filter_name (partial, case-insensitive match) and parent_id (folder's URL number, null for top-level), enhancing the schema's information.

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

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

The description clearly states that it lists document folders in an organization, including nested folders. It specifies the return is summary metadata, and differentiates from sibling list tools by focusing on folders.

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 advises using this tool to discover folder IDs for itglue_create_document or to browse the document tree. It explains filter_name and parent_id behavior but does not explicitly contrast with other list tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral details: it discloses that only summary metadata is returned, explains the second query for nested documents, and notes that results are merged up to 2x page_size. This fully informs the agent of the tool's behavior.

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

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

The description is three sentences long, front-loading the primary purpose and immediate alternative. Each sentence provides distinct, useful information without redundancy, making it highly concise and structured.

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

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

Given the tool's complexity (7 params, output schema present), the description covers the most important behavioral aspects: nested document handling, filter behavior, and the alternative tool. It could be slightly improved by explicitly addressing pagination or response format, but overall it is sufficiently complete.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by specifying that filter_name matches partially and case-insensitively, and that the page_size parameter affects the merged result size. However, it does not enhance semantics for all seven parameters.

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

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

The description clearly states the tool lists documents in an organization, including nested folders, and explicitly distinguishes it from itglue_get_document by noting that only summary metadata is returned. This differentiation from sibling tools is strong.

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 on when to use this tool (for listing documents) and points to itglue_get_document as an alternative when full content is needed. It also explains the default behavior and the second query for nested documents, but does not explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds context about position order and bounded previews, aligning with read-only nature. No contradiction.

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

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

Two concise sentences: first states purpose, second provides usage guidance and linkage. No wasted words.

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

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

Complete for a list tool with good annotations and output schema. Explains output content and when to use sibling tool for full data.

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

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

Schema description coverage is 100%; description does not add parameter-level details beyond what schema provides. Baseline 3 applies.

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

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

The description uses specific verb 'list' and resource 'sections of a document', includes ordering and content previews, and differentiates from sibling tools like itglue_get_document_section.

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 recommends itglue_get_document_section for full content, and mentions section IDs are needed for update/delete. Does not explicitly state when not to use, but implication is clear.

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

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

Annotations already declare read-only and idempotent. Description adds that returned items are previews with truncated/stripped values, and directs to get for full data. No contradictions.

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

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

Two sentences, no fluff. Each sentence adds value: purpose and optional restriction, then required ID and sibling tool reference, then preview behavior and alternative for full values.

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

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

With annotations and output schema, description covers purpose, key limitation (previews), and how to get more detail. Lacks mention of pagination or error cases, but sufficient for a list tool.

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

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

Schema covers 100% of parameter details. Description adds context about the type ID relationship but does not elaborate on page_size, response_format, or organization_id beyond schema defaults.

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

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

Clearly states 'list flexible assets of a given type' with optional organization filter. Distinguishes from itglue_get_flexible_asset (full values) and directs to itglue_list_flexible_asset_types for type IDs.

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

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

Explicitly says when to use this tool (list by type) and when to use alternatives (get for full values). Mentions required type ID and how to find it, but does not explicitly state when not to use (e.g., for filtering by something else).

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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral specifics: filter_name matches partially and case-insensitively, and output format options. This adds value beyond the annotations.

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

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

Two concise sentences with no waste. Front-loaded with purpose and usage, then adds filtering details and sibling references. Every sentence earns its place.

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

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

Given 4 parameters, 100% schema coverage, rich annotations, and an output schema, the description covers purpose, usage, filtering behavior, output format, and related tools. It is fully complete for the agent's needs.

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

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

Schema coverage is 100%, but the description enriches meaning: explains filter_name's partial case-insensitive matching and response_format's human-readable vs. structured output. This goes beyond the schema descriptions.

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

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

The description clearly states 'List flexible asset types' with specific verb and resource. It distinguishes from sibling tools by mentioning itglue_list_flexible_assets and itglue_get_flexible_asset_type, making its purpose unique.

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

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

Explicitly advises to use this tool to find the type ID required by itglue_list_flexible_assets. Also recommends itglue_get_flexible_asset_type for field definitions, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by noting pagination, summary fields on list items, and case-insensitive partial name matching, which go beyond annotations.

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

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

Four sentences, no filler, essential information front-loaded. Every sentence adds value: purpose, usage context, filtering behavior, pagination, and pointer to full record tool.

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

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

Given the presence of an output schema (despite not shown), the description adequately covers pagination, filtering, and relational context. No gaps identified.

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

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

Schema coverage is 100%, but description adds meaningful details: filter_name matches partially and case-insensitively, filter_id is exact, and sort prefix '-' indicates descending. This enriches 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 tool's purpose: 'Search and list IT Glue organizations.' It also specifies its role as a prerequisite for other tools (finding organization ID), distinguishing it from siblings like itglue_get_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 advises using this tool first to obtain organization IDs needed by document and flexible-asset tools, providing clear usage context. It does not explicitly exclude other list tools but indirectly guides when to use get_organization for full records.

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

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

Annotations provide idempotentHint and destructiveHint. Description adds key behavioral context: the effect of making the document visible to users. Could mention prerequisites or reversibility, but given annotations, additional value is present.

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

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

Single sentence, front-loaded with verb and outcome, zero 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?

Low complexity tool with 1 param and good annotations. Description covers main purpose but omits details like whether draft state is required or if publishing is reversible. Still adequate.

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

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

Schema coverage is 100% for single parameter document_id. Description does not add meaning beyond schema; schema already describes it as 'The document ID to publish'.

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

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

Description clearly states verb 'publish', resource 'draft document', and outcome 'making it visible to users with access'. Distinguishes from sibling tools like create, update, delete, get.

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?

Implicit usage: publish a draft when ready to make it visible. No explicit when-to-use, when-not-to-use, or alternative tools mentioned 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 indicate idempotentHint=true and destructiveHint=false. The description adds 'metadata only', clarifying the scope of the operation. No additional behavioral details (e.g., auth needs, side effects) are provided, but the existing context is sufficient.

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

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

The description is two sentences, concise, and front-loaded with the primary purpose. Every sentence adds value.

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

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

The description explains the scope (metadata only) and points to sibling tools for other operations. It lacks details about the response format or side effects, but the tool is simple and well-contextualized by the schema and annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond what the schema already provides for parameters. 'Rename a document' implies the name parameter's role, but the schema already describes it as 'New document name'.

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 renames a document (metadata only) and explicitly distinguishes it from itglue_update_document_section for content changes. The verb 'Rename' and resource 'document' are specific.

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

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

The description explicitly states when to use this tool (rename metadata) and when to use an alternative (itglue_update_document_section for content), providing clear 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?

Beyond annotations (idempotent, non-destructive), description clarifies partial update behavior ('Only provided fields change'), type immutability, and inline image embedding capability, adding contextual behavioral traits.

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

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

Two sentences concisely convey purpose, constraints, and an important detail about image embedding; no redundancy or filler.

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

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

Covers key aspects: what can be updated, partial update nature, and type restriction. Lacks mention of prerequisites or potential side effects, but for a partial update tool with rich schema, it is adequate.

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

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

With 100% schema coverage, description reinforces parameter meanings by listing them and explaining that only specified fields are updated, adding value beyond the schema's individual 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?

Description clearly identifies the action (Update) and resource (section), lists specific updatable fields (content, heading level, duration, position), and distinguishes from sibling tools like create/delete by focusing on 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?

Indicates that only provided fields change and section type is immutable, implying partial update semantics, but does not explicitly state when to use this tool over alternatives (e.g., create vs update) or provide when-not 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 indicate mutation (readOnlyHint=false) and idempotency. The description adds the crucial behavior of wholesale replacement, which is 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?

Two-sentence description: first states action, second provides critical caveat. Front-loaded and no unnecessary words.

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

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

Covers essential behavior for using the tool correctly, given the complexity of wholesale replacement. Lacks mention of response_format parameter, but schema covers it adequately.

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

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

Schema coverage is 100% and already describes traits as complete set and response format. The description reinforces the warning but adds minimal new meaning beyond the schema.

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

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

The description clearly states the tool updates a flexible asset's traits, matching the name and title. Distinguishes from siblings like create or delete flexible 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?

Explicitly warns that IT Glue replaces traits wholesale, instructing the user to fetch the asset first and send all traits to avoid clearing omitted ones. Provides critical usage guidance.

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