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

Annotations already convey readOnlyHint=false, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavior beyond those: where the file lands (Attachments side panel, not document body), server-side fetch-and-encode behavior for url, the 25 MB size cap, and the stdio-only restriction on file_path. It does not contradict the annotations (annotation_contradiction=false); it substantially enriches them.

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

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

The description is front-loaded with purpose, then differentiates from the sibling, then layers constraints in a logical order (source exclusivity, file_name guidance, size limit). Each sentence carries unique information — no filler or repetition of the schema. It is dense, but the length is justified by 7 parameters and a sibling ambiguity.

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 create operation with 7 parameters, no output schema, and a near-overlapping sibling, the description covers the essentials: placement behavior, source exclusivity, size limit, transport restriction, and sibling routing. The main gap is return-value expectations (no explanation of what a successful call returns, though response_format hints at markdown/json output). Overall, an agent has enough to invoke this 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema: it makes explicit the one-of exclusivity among content_base64, url, and file_path (which the schema does not express as a oneOf constraint), states the file_name inference rule from url/file_path, and adds the 25 MB limit absent from the schema. This compensates for and clarifies ambiguities the schema leaves open.

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 opens with a specific verb+resource: 'Attach a file ... to a record' and enumerates the supported record types (document, flexible asset, configuration, etc.). It differentiates explicitly from the sibling itglue_create_document_image by clarifying the attachment appears in the Attachments side panel, not in a document body. An agent can immediately distinguish this tool from its overlapping sibling.

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 gives explicit when-not-to-use guidance: 'To place a picture inside a document ... use itglue_create_document_image instead.' It also states the mutually exclusive source constraint ('Provide exactly one source') and flags that file_path works only on stdio runs. These are concrete, actionable routing and precondition rules.

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 already indicate this is a mutating (readOnly=false), non-idempotent operation, but the description adds crucial behavioral context: IT Glue strips base64/data URIs and S3 URLs from section content, the 25 MB limit, the verbatim use of inline_resource_url, and the automatic append behavior when append_to_section_id is passed. These are not inferable from the schema or annotations.

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

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

The description is dense and packed with necessary details, organized into numbered placement options and warnings. It is not as concise as a two-sentence definition, but every sentence earns its place; the front-loaded purpose and placement taxonomy make it navigable.

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 tool with 8 parameters, two placement modes, and no output schema, the description is remarkably complete. It covers source exclusivity, size limits, forbidden content types, the returned relative URL, how it interacts with sibling tools, and the append option—everything an agent needs to call it 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?

Although schema coverage is 100%, the description adds essential semantics beyond the schema: it enforces the 'exactly one source' rule among content_base64, url, and file_path; clarifies that gallery_id is the document_gallery_id shown on a Gallery/Step section; explains file_name inference and the data: URI prefix stripping; and specifies that append_to_section_id is inline-only. This meaningfully reduces the chance of incorrect invocation.

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 opens with a specific verb and resource—'Upload a picture INTO a document'—and immediately distinguishes itself from the sibling itglue_create_attachment by stating it is the only way to get an image to render in the body. This makes the tool's scope unmistakable.

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 explicitly names the alternative (itglue_create_attachment) and explains why you would choose this tool instead. It also gives conditional guidance for the two placements (inline vs. gallery), including when to use append_to_section_id versus manually inserting the returned URL via itglue_create_document_section or itglue_update_document_section.

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=false, destructive=false, and idempotent=false, but the description adds substantial behavioral detail: Heading requires level 1-6, Gallery has no content, Step has optional duration, and IT Glue strips base64/data and S3 URLs while allowing public https images. It also warns that attachments never render in the body. This is rich, non-obvious behavior 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 core action is front-loaded and the type breakdown is compact. The IMAGES paragraph is somewhat long and dense, but every sentence carries useful behavioral information. It could be tightened, but there is no wasted text 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?

For a complex 7-parameter tool with no output schema, the description is remarkably complete. It covers all four section types, conditional parameter requirements, the Gallery follow-up path, image embedding rules, and attachment behavior. The remaining parameter details are well covered by the schema, and the description even implies that the section response exposes document_gallery_id for later image uploads.

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 already strong, but the description adds valuable conditional semantics: level is required specifically for Heading, duration applies only to Step, and Gallery accepts no content. It also explains how content relates to the image upload workflow and inline_resource_url. The description meaningfully extends the schema rather than merely repeating it.

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 opens with a specific verb and resource, 'Add a section to a document', and enumerates the four section types, making the tool's scope unmistakable. It also clearly distinguishes itself from sibling tools like itglue_create_document and itglue_create_document_image by naming them in the workflow. An agent can understand exactly what this tool does without opening the schema.

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 gives clear conditional usage: Gallery sections are followed by itglue_create_document_image, and Text/Step images require prior upload via itglue_create_document_image. It does not explicitly contrast with update/delete/list section siblings, but the creation context and workflow pointers are strong. The guidance about image URL formats also helps the agent decide how to supply content.

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?

Even though destructiveHint=true already signals destructive behavior, the description adds substantial specifics: all size variants are removed, the action cannot be undone, stale <img> tags survive until the section is next saved, and the section-update mitigation. This far exceeds what the annotations alone 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?

Two dense sentences with no filler: the critical permanence warning is front-loaded, and the orphaned-reference caveat plus remediation earn their 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?

For a single-required-parameter destructive action with no output schema, the description covers what gets destroyed, irreversibility, downstream side effects on section HTML, and the explicit cleanup action. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% and both parameters already have clear descriptions (image_id as the target, document_id as optional index refresh). The free-text description adds no additional parameter meaning, so the baseline 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?

States a specific verb and resource: 'PERMANENTLY delete a document image (all size variants)'. The all-variants detail and the resource type distinguish it from sibling deletes like delete_document_section, delete_documents, and 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 makes the deletion context explicit and gives clear follow-up guidance: broken <img> references persist until the section is saved, and itglue_update_document_section should be used for an immediate clean result. It stops short of formally listing when-not-to-use or alternative deletion paths.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering safety and idempotency. The description adds valuable behavioral context about the response format: section content is HTML, markdown output converts to plain text, images are represented as relative paths or listed by ID, and the possibility of truncation. This goes beyond the annotations and informs the agent about output quirks.

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 compact and front-loaded: it starts with the action and resource, then adds key details about output format and truncation handling. Every sentence is informative with no wasted words. It efficiently covers the most important points an agent needs to know.

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

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

Given the tool has an output schema, the description doesn't need to explain return values in detail. The description covers the main functionality, output format nuances, and fallback to section-level retrieval. It could mention pagination or limits more explicitly, but the truncation hint partially covers that. The tool is relatively simple with only two parameters, so the description 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%, so the schema fully documents both parameters (document_id and response_format). The description adds meaning by explaining the markdown output's treatment of HTML content and images, which is not in the schema. This is useful but not essential for invoking the tool correctly; the schema already provides the parameter 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 tool retrieves a specific document by ID, including all its sections and content. It distinguishes itself from the sibling itglue_get_document_section by explaining that this tool fetches the whole document, and that individual sections can be fetched separately. This is a specific verb+resource with clear scope.

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

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

The description provides clear context on when to use this tool: to get a full document with sections. It also gives a practical usage hint: if the response is truncated, use itglue_get_document_section instead. It doesn't explicitly state when to prefer other tools like itglue_list_documents, but the scope is well defined enough for an agent to select it appropriately.

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, and destructiveHint=false. The description adds genuinely useful behavioral context: the presigned download URL is valid for ~1 hour, and the response includes an embeddable inline_resource_url. This goes beyond what the annotations alone convey, though it stops short of describing error cases or response_format 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?

Two sentences with no filler. The core action and returned fields are front-loaded, and the second sentence adds only the needed ID-location context. Every phrase 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?

For a read-only single-resource getter with rich annotations, a complete input schema, and an output schema, the description covers everything an agent needs: what it returns, how to find the ID, and the URL expiry caveat. No important calling 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?

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning to image_id by explaining how image IDs appear in section HTML and image lists, which helps the agent know what value to pass. response_format is fully documented in the schema and needs no additional prose.

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 opens with 'Get one document image by ID,' a specific verb and resource, and enumerates the exact returned fields (file name, size, owning document/gallery, inline_resource_url, presigned download URL). This makes the tool's function unambiguous and clearly distinct from siblings like itglue_get_document or itglue_delete_document_image.

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 makes it clear this is for retrieving a single image when an image_id is known, and it elaborates on where to find those IDs ('last path segment of <img src=...>' and 'Gallery/Step section image lists'). It does not explicitly name alternatives or exclusions, but the retrieval-by-ID context is strong enough to guide correct use.

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 behavior beyond the readOnly/idempotent/openWorld annotations: HTML is the wire format, markdown output converts to plain text, inline images use relative paths that must be preserved verbatim, and the JSON record includes rendered_content with temporary S3 URLs. This tells the agent about content transformations and special fields the annotations alone would not reveal.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the second sentence packs several important caveats (image paths, verbatim preservation, rendered_content, S3 URLs) efficiently. Every clause 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?

With an output schema present, the description doesn't need to enumerate return fields. It covers the key operational gotchas: content format conversion, inline image path syntax, editing constraints, and the difference between markdown and JSON output. Nothing needed for correct invocation 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the response_format behavior: markdown output is plain text and JSON output includes rendered_content with temporary S3 URLs. This gives practical detail about what the parameter values produce.

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 and resource ('Get one document section with its full content'), clearly distinguishing this from listing multiple sections (itglue_list_document_sections) or fetching a whole document (itglue_get_document). The singular scope is explicit and immediately identifiable.

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 phrase 'Get one document section with its full content' gives clear context for when this tool is appropriate—retrieving the full body of a single section—and implicitly differentiates it from list_document_sections and get_document. It doesn't explicitly name alternatives or state when not to use it, which prevents a 5, but sufficient guidance is present.

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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral details: results come in position order, list items carry summary fields with a bounded content_preview, and Gallery/Step items include document_gallery_id and images. 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 compact and front-loaded with the primary purpose. Every sentence contributes: main behavior, key output details, special item behavior, and a pointer to the sibling for full content. No filler or redundant restatement of the tool name.

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 and annotations already declare read-only/idempotent behavior, the description provides the remaining context an agent needs: ordering, preview bounds, section ID purpose, gallery_id linkage for image creation, and when to call get_document_section instead. This is 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%, so parameters are already documented in the input schema. The description does not add new parameter-level semantics, but it does clarify the shape of the returned items, which is helpful context. This meets the baseline for full 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 uses a specific verb and resource: 'List the sections of a document in position order, with content previews and section IDs'. It also differentiates itself from itglue_get_document_section, which is for full content, and positions itself as the prerequisite for update/delete operations on 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?

It explicitly states when to use this tool: to obtain section IDs for update/delete operations, and when to use the alternative: 'Use itglue_get_document_section for full content.' This gives the agent clear routing guidance against its sibling 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 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds critical behavioral details beyond those: content replaces the whole HTML, unkept <img> tags are lost, and base64/data URIs and S3 URLs are stripped by IT Glue. This is exactly the kind of side-effect disclosure an agent needs before invoking a mutating tool.

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

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

The description is four focused sentences with no filler. It front-loads the core purpose, then immediately covers partial updates, destructive HTML replacement, and the image-upload workflow. Every sentence earns its place and contributes either selection or invocation guidance.

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 7-parameter update tool with no output schema, the description covers the non-obvious behaviors thoroughly: whole-HTML replacement, image-tag preservation, section-type immutability, and URL constraints. It does not explicitly describe the return value, but the response_format parameter and schema already indicate output choices. A small note on what the response contains would make it fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful value on top. It clarifies the content parameter's replacement semantics, warning to preserve existing image tags, and maps the field list to the affecting parameters. It does not add much beyond what the schema already states for level, duration, or sort, but the content-related nuance justifies above baseline.

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 opens with a specific verb ('Update') and resource ('a section') and enumerates exactly which fields change: content, heading level, duration, or position. It also explicitly states what it cannot do ('the section type cannot be changed'), which distinguishes it from create/delete/get section tools. This leaves no ambiguity about the tool's purpose.

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 gives clear operational context: fetch current content before updating, and use itglue_create_document_image for adding pictures. It also names the sibling shortcut (append_to_section_id) for the image workflow. However, it does not explicitly contrast with broader siblings like itglue_update_document or state when not to use this tool beyond the section-type limitation.

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.