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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds valuable context beyond annotations: it explains the operation is a 'soft delete' that hides from normal views but remains recoverable, and warns of 'HIGH-IMPACT' with a user-confirmation requirement. No contradiction.

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

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

The entire guidance is conveyed in one compact sentence with a warning prefix. Important scoping (recoverability) and the alternative action are front-loaded ahead of the procedural detail. No 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?

This is a simple one-parameter tool with no output schema, and the annotations carry the safety profile (destructive, read-only, idempotency). The description covers purpose, effect, alternatives, and a mandatory confirmation step. Nothing an agent needs to call it correctly 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?

The input schema has 100% description coverage for the single parameter (document_id), so the schema fully documents the parameter. The description does not add extra meaning beyond what the schema provides, but no extra meaning is needed. 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 states a specific verb ('Archives') and resource ('IT Glue document'), and clarifies the nature of the action ('soft delete — hides it from normal views but keeps it recoverable'). It also distinguishes itself from the sibling tool 'unarchive_document' by explicitly naming the reverse operation.

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

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

The description explicitly names the alternative tool (unarchive_document) for restoration, and provides a clear condition for invoking this tool ('Confirm with the user before invoking'). The soft-delete clarification also guides when not to use it (when permanent deletion is desired).

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 useful behavioral context beyond the annotations by specifying that the file must be passed as base64 without a data: prefix. It also clarifies the resulting artifact is a downloadable attachment, not an embedded image. Annotations already communicate readOnlyHint=false, so the write nature needs no further emphasis.

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

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

The description is two sentences with no filler. It front-loads the purpose, then gives the sibling contrast and the one crucial input caveat. 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?

For a relatively simple create operation with a complete schema and annotations, the description is adequately complete. It covers the core purpose, the main alternative, and the critical base64 formatting detail. It does not mention file size limits or response format, but these are not required for tool selection and no output schema is provided.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description's base64 note restates what the schema's content field already says, adding no meaningful new parameter-level information. This matches the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Attach a file to an IT Glue record.' It then explicitly distinguishes itself from create_document_image by contrasting a downloadable attachment with an in-body image, making the tool's purpose clear relative to a close 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 names the key alternative (create_document_image) and states the difference: this tool adds a downloadable attachment, whereas the sibling adds an image in the document body. This effectively tells an agent when to choose this tool, though it does not explicitly phrase it as a conditional 'use this when' statement.

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?

With no annotations, the description carries the full behavioral burden and does so well by disclosing the interactive prompt, the API-key-first then JWT fallback for folder enumeration, and the prompt's accepted input forms. It also explains the root-creation behavior for skip_folder_prompt. It does not describe return values or error cases, but the core side-effect behavior is transparent.

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?

Every sentence earns its place: the purpose is front-loaded, followed by prompt behavior, fallback ordering, and the root-creation escape hatch. The length is justified by the complexity of the folder-picking behavior, with no redundant or promotional language.

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 annotations and no output schema, the description covers the nontrivial invocation details an agent needs: the required container context, the interactive prompt condition, the enumeration fallback chain, and the way to bypass prompting. It is complete enough to select and call the tool correctly without opening 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?

The schema already documents all five parameters at 100% coverage, so the description did not need to restate them. It adds genuine value by explaining how document_folder_id interacts with the folder prompt and precisely what skip_folder_prompt=true does.

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 opening sentence names a specific verb and resource ('Create a new document in IT Glue for an organization'), which clearly distinguishes this from sibling section/file tools. It also reveals the target container (organization), so an agent can separate it from search/get/list document tools at a glance.

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 conditional instructions: if neither document_folder_id nor skip_folder_prompt is supplied, the agent should expect a folder prompt, and it states the escape hatch of skip_folder_prompt=true. It does not, however, name sibling alternatives or explicitly say when not to use this tool, so it stops short of a full 5.

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

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

Beyond the annotations, the description discloses non-obvious IT Glue sanitisation behavior and the exact base64 format required, including stripping the data: prefix. It also warns that this is the only way to embed an image in a document body, which annotations alone would not 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?

Every sentence earns its place: purpose, encoding requirement, sanitisation rationale, and next workflow step. The most important information is front-loaded and the rationale is compact rather than padded.

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 three-parameter upload tool with no nested objects, the description covers purpose, format constraints, environmental behavior, and the required follow-up publish step. The absence of an output schema is not a significant gap because the workflow continuation is stated.

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 explains document_id, file_name, and content. The description reinforces the raw-base64 requirement but adds little beyond what the schema's content property already states.

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 action and resource: 'Upload an image into an IT Glue document so it can be shown inline in the document body.' This clearly distinguishes the tool from sibling document-editing tools and states the intended outcome.

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

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

The description explains why this tool is necessary (sanitiser strips <svg> and rejects data: URIs) and gives the follow-up step 'Call publish_document after editing sections to reference it.' It does not explicitly name create_attachment as an alternative for non-inline images, so it stops short of full when/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?

With no annotations provided, the description carries the behavioral transparency burden. It discloses that content is HTML and that the tool is a write/mutation operation (implied by 'Add'), and it references the publish workflow. However, it doesn't disclose whether sections must be published to be visible, what happens to unpublished changes, or whether there are limits on section count or size.

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

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

Three short sentences, each earning its place: the action statement, the section type enumeration, and the important post-edit workflow instruction. No filler or redundant content.

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

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

For a simple 3-parameter creation tool, the description covers the essentials. The workflow hint about publish_document is valuable. However, there's no output schema and no annotation coverage, so the agent doesn't know what the response will contain or whether an ID is returned for the created section. The publish_document reference partially compensates, but the missing post-call behavior details leave a 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description adds a small amount of behavioral context by noting that content is HTML and clarifying the section_type enum values map to class names, but it doesn't add meaningfully beyond the schema's own descriptions.

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

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

The description clearly states the verb ('Add'), the resource ('a new section to an IT Glue document'), and enumerates the two section types with their underlying class names ('heading' for Document::Heading, 'text' for Document::Text). This distinguishes it from sibling tools like update_document_section and 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 implies when to use it (when adding sections to documents) and gives explicit workflow context by telling the agent to call publish_document after editing. It doesn't explicitly state when not to use it or contrast with update/delete siblings, but the guidance about publish_document provides clear usage context.

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?

There are no annotations, so the description must carry the full burden of describing side effects and operational context. It states that a location is created and that country_id is typically required, but it does not disclose response behavior, authentication needs, or potential impacts on existing data. This is a significant gap for a mutating tool.

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

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

The description is two sentences and about 30 words, with the primary verb-resource pair in the first sentence and the key requirement in the second. There is no filler, placeholder language, or repeated schema content beyond the country_id context.

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

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

For a 12-parameter create tool, the schema covers the input surface well and the description gives the central new-location use case. However, with no output schema and no annotations, an agent is left without information about the response shape, authorization needs, or what happens after creation. This is adequate overall but not 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?

All 12 parameters already have descriptions in the input schema, so the tool description does not need to restate them. The only added parameter guidance is the aggregate note about country_id, which mostly reinforces the schema's existing property description. Baseline 3 is appropriate because the schema carries the parametic load.

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 (Create) and resource (location) and clarifies it as a physical address/site for an organization. This clearly distinguishes it from get_location, update_location, and search_locations without needing to inspect schemas.

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 clearly frames this as the create operation for a new location, versus modifying or retrieving an existing one. It also gives the key precondition that a name and typically a country_id are required, so an agent knows what must be supplied before calling.

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 mark destructiveHint=true and readOnlyHint=false, but the description adds critical context: the action is irreversible, cannot be undone, and requires user confirmation. It also instructs calling publish_document afterward,which annotations do not convey.

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

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

The description is exceptionally concise, with the most important warning front-loaded. Every sentence carries meaningful safety or workflow information with no 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 two-parameter destructive action with annotations already covering the destructive nature, the description fully covers what an agent needs: it warns of irreversibility, mandates user confirmation, and names the required follow-up action. No output schema is needed for a delete 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 the parameter descriptions already fully document document_id and section_id. The tool description does not add further parameter-level detail, but none is needed 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?

Description states a specific verb ('deletes') and resource ('section from an IT Glue document') and emphasizes permanence. This clearly distinguishes it from sibling tools like update_document_section, create_document_section, and list_docoment_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?

Provides explicit operational guidance: confirm with the user before invoking and call publish_document after editing. It does not explicitly contrast with update/create alternatives, but the destructive framing and publish instruction sufficiently imply the intended deletion workflow.

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?

No annotations are present, so the description bears the full burden of behavioral disclosure. It only states the basic operation and provides no context about response format, errors, authentication, or side effects. For a simple read operation this is minimal but acceptable; still, it lacks depth.

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 directly conveys the resource and lookup method. There is no wasted text, and the core scoping information appears immediately.

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 tool is simple with one parameter and no output schema, so the description covers the essential call. However, it lacks guidance on when to use this instead of search_configurations and does not describe the expected return value, leaving moderate room for ambiguity.

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

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

Schema description coverage is 100%, with the id parameter already described as 'The configuration ID'. The description adds no extra semantic value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (Get), the resource (configuration/device/asset), and the scope (by ID from IT Glue). It does not explicitly differentiate from the sibling search_configurations, but the 'by ID' phrasing implies a single-object retrieval as opposed to search.

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 about when to use this tool versus alternatives like search_configurations. The description implies it is for direct ID-based retrieval, but it never states to use search_configurations when the ID is unknown or when filtering is required.

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?

No annotations are provided, so the description bears the full burden of behavioral disclosure. It discloses only the operation itself — it does not state what the response contains, how not-found cases behave (e.g., 404 vs empty result), or whether archived documents are retrievable given that archive_document/unarchive_document exist among siblings. 'From IT Glue' provides source-system context but no 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?

The description is a single nine-word sentence with zero filler. The verb, resource, and identifier method are front-loaded, and every word contributes meaning.

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 tool itself is simple — two fully documented parameters, no nested objects, no output schema — so a short description is defensable. However, the large sibling list includes closely related document tools (search_documents, create_document, list_document_sections, publish_document) and the description gives the agent no help choosing among them, nor any indication of what the returned document object looks like. Adequate for basic invocation, but with clear gaps.

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

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

Schema description coverage is 100%, with both 'id' and 'organization_id' already documented in the input schema. The description's 'by ID' phrasing merely echoes the schema's 'The document ID' without adding format, syntax, or relationship details, so the baseline of 3 applies — 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 states a specific verb ('Get'), a resource ('document'), and an identification method ('by ID'), making the core operation unambiguous. However, it does not explicitly differentiate itself from the sibling tool search_documents — the implicit contrast between 'specific document' and 'search' is present but not made explicit.

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?

There is no guidance on when to use this tool versus alternatives. The sibling list contains search_documents, which is the obvious alternative for when a document ID is not known, but the description never references it or states any when/when-not conditions. The phrase 'by ID' faintly implies the caller must possess an ID, but this is inference rather than explicit 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?

No annotations are provided, so the description carries the transparency burden. 'Get' plus 'including its full address and phone number' indicates a read operation with no side effects, but auth needs, missing-ID behavior, and full response details are not disclosed. This is adequate for a simple GET but not comprehensive.

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

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

The description is a single sentence with no filler, opening with the action and target. It adds useful result detail without excessive verbosity.

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 one-parameter GET with no output schema, the description effectively conveys the scope and primary returned fields. It could mention error/not-found behavior or authentication requirements, but the low complexity makes the current description largely 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?

The input schema already describes id as 'The location ID' with 100% coverage. The description adds only that the ID identifies a specific IT Glue location, providing no additional format or semantic detail beyond the schema.

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

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

The description states 'Get a specific location by ID from IT Glue', naming the verb, resource, and retrieval mode. This clearly distinguishes it from search_locations, which searches rather than fetches a known ID, and mentions key returned data (address and phone number).

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 'specific location by ID' implies this tool is appropriate when the caller already has a location ID. However, it does not explicitly contrast with search_locations or state when to prefer an alternative, so usage guidance is implied rather than explicit.

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

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

No annotations are present, so the description carries the full burden. It only restates that it gets an organization by ID; it does not disclose return format, not-found/error behavior, auth requirements, or any rate-limit constraints. This is minimal disclosure for a tool without annotation support.

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 one clean sentence with no wasted words. It front-loads the verb and resource and includes the key scoping qualifier 'specific ... by ID' and the source system 'IT Glue'.

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 one-parameter get-by-ID tool, the description is minimally adequate. However, there is no output schema, so the agent is not told what the tool returns or how it handles a missing ID. A sentence about the response payload or error behavior would make it 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?

The input schema already covers the single `id` parameter with 100% coverage and a description. The tool description's 'by ID' adds no extra meaning beyond what the schema provides, so the 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 states a specific verb and resource: 'Get a specific organization by ID from IT Glue'. It clearly differentiates this direct fetch from sibling search_organizations by emphasizing 'specific' and 'by 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?

There is no guidance about when to use this tool versus alternatives. It does not mention search_organizations for lookup-by-criteria, no prerequisites, and no exclusions. The only implicit signal is 'by ID', which is not explicit enough for routing an agent.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose the meaningful trait that the actual password value is returned, which is a sensitive-data signal. However, it does not explicitly state that the operation is read-only, how to suppress the password via show_password, or provide any caution about handling the returned secret.

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 the action and resource, and every word contributes to understanding. It efficiently conveys the core purpose and the key caveat about password inclusion without any fluff.

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

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

For a simple get-by-ID tool with two parameters and no output schema, the description covers the core behavior but leaves gaps. It does not mention when to use the tool or warn about the sensitive nature of the output, and without annotations the safety profile is under-specified. It is minimally viable but not 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 description coverage is 100%, so the baseline is 3. The phrase 'includes the actual password value' loosely maps to the show_password parameter, but the schema already documents this parameter and its default value. The description adds no additional semantic meaning beyond what the input 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 uses the specific verb 'Get' and names the resource as 'a specific password entry by ID from IT Glue', which clearly identifies the operation. The added note that it 'includes the actual password value' distinguishes it from search_passwords and other getters, making the tool's purpose 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?

No guidance is given for when to use this tool versus alternatives. It implies the agent must already have an ID, but it never says to use search_passwords when the ID is unknown, nor does it mention any exclusions or conditions for choosing this tool over a sibling.

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?

No annotations are provided, so the description carries the full burden. It discloses the operation as a connectivity check that fetches organization types, implying a read-only network call, but it does not describe return values or failure behavior. This is adequate for a zero-parameter health check but not rich.

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

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

A single sentence that front-loads the action and gives just enough mechanism detail. Every word earns its place with no 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 tool with no inputs, no output schema, and a unique purpose among siblings, the description covers the essential context. It omits explicit success/failure semantics, but the health-check intent makes that 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 tool has zero parameters and 100% schema coverage with an empty properties object, so there is no parameter documentation burden for the description to carry. Baseline 4 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 the exact purpose ('Check connectivity to IT Glue API'), the resource (IT Glue API), and the mechanism (fetching organization types). This clearly distinguishes it from the CRUD and search sibling 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?

The description clearly implies when to use the tool: whenever API connectivity needs verification. It is unique among siblings, so no alternative routing is needed, though 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?

With no annotations provided, the description itself must convey behavior. The verb 'List' makes the read-only nature reasonably clear, and mentioning download URLs describes the key output. But it does not disclose pagination, response envelope, error cases, or any permission requirements that may apply to accessing attachments.

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, concise sentence that leads with the action, names the target resource, and states the valuable output detail. Every word contributes to understanding the tool's purpose.

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

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

The tool is simple, requiring only two parameters that are fully documented in the schema, and the description covers what the tool returns (attachment download URLs). Since there is no output schema, it would be slightly stronger to mention pagination or the exact response shape, but for a straightforward list operation the description 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?

Schema description coverage is 100%, so the schema already documents both resource_type and resource_id well. The description adds no additional parameter semantics beyond what the enum and field docs provide, matching 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 states a specific verb ('List') and resource ('files attached to an IT Glue record'), and it adds the useful output detail that download URLs are included. This clearly differentiates the tool from sibling resource-specific getters and from create_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 implies when to use the tool: when an agent needs the attachments (with download URLs) for a given IT Glue record. However, it gives no explicit guidance about when not to use it or what alternative sibling tools (e.g., get_document, get_configuration) might offer instead.

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?

With no annotations, the description carries the burden of behavioral disclosure and does add meaningful context: API key authentication, JWT fallback, configuration via ITGLUE_JWT or X-ITGlue-JWT header, and the 2026 tenant rollout condition. It does not cover pagination or error behavior, but the most operationally relevant quirks are surfaced.

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

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

Three purposeful sentences with no filler; the first states the core function, and the next two add necessary authentication and availability context. The second sentence is slightly dense, but every part 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 listing tool with no output schema and all parameters documented, the description covers purpose, return shape, authentication fallback, and rollout availability. It is missing explicit guidance on when to prefer sibling tools and some pagination details, but these are relatively minor for this 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 the schema already documents all four parameters. The description adds only output context ('names and IDs') and does not provide additional meaning for name, page_size, page_number, or organization_id beyond what is 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?

States a specific verb ('List'), a specific resource ('document folders'), and a scope ('for an organization'), while also mentioning the output ('names and IDs'). It is clear and distinct, but it does not explicitly contrast with sibling tools like list_document_sections, leaving the differentiation to the resource name.

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 intended use is implied: retrieve document folder names and IDs for an organization when the Document Folders resource is available. It does not explicitly state when to use this tool versus alternatives such as list_document_sections or search_documents. The tenant-rollout caveat is an availability condition, not a selection guideline.

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?

With no annotations provided, the description must carry the behavioral burden. It communicates a read-only, non-destructive action through 'List' and 'read document content,' and discloses the ordering guarantee ('in order'). It does not mention auth requirements or rate limits, but for a simple list operation the disclosure is adequate.

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

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

Two concise sentences with no filler. The primary behavior is front-loaded, and the usage hint occupies the second sentence without redundancy. Every word contributes 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 one-parameter, read-only list operation with no output schema, the description is complete. It names the resource, the action, the ordering behavior, and the recommended usage context. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the single parameter 'document_id' is already documented as 'The document ID.' The description adds no meaningful parameter-level detail beyond that, so the 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 states a specific action ('List all sections') on a specific resource ('an IT Glue document') and adds the ordering detail 'in order.' This clearly distinguishes it from siblings like list_document_folders and get_document.

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 'Use this to read document content before editing' gives clear, actionable guidance on when to invoke the tool. It does not name alternatives or exclusion cases, but the intended pre-edit read context is explicit.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly communicates the behavior as a read-only enumeration ('List all') and reveals that the output is useful for discovering type IDs, which adds context beyond the literal listing action.

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

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

The description is two sentences with no wasted words. The core action is front-loaded, and the usage direction is placed immediately after, making it easy for an agent to parse and act on.

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 list tool with one optional parameter and no output schema, the description is complete: it names the resource, explains the purpose, and tells the agent exactly where it fits in the workflow. No critical guidance 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?

The input schema fully documents the single optional parameter, including that omitting it returns global types. The description does not add additional parameter-level detail, but none is needed because schema coverage is 100%.

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 begins with a specific verb and resource: 'List all flexible asset types defined in IT Glue.' It also clarifies the tool's role in the broader workflow by stating it should be called first to discover type IDs before using search_flexible_assets, distinguishing it from that 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 usage guidance: 'Call this first to discover type IDs before using search_flexible_assets.' This clearly communicates when this tool should be used and how it relates to an alternative 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?

No annotations are provided, so the description carries the full burden. It does disclose that publishing makes section changes visible, which is useful behavioral context. However, it does not mention side effects, permissions, idempotency, or whether publishing affects already-published sections, so the disclosure is only partial.

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 short sentences with no filler. The action and purpose are front-loaded, and the usage guidance is a direct, imperative follow-up. 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?

For a simple, one-parameter tool with no output schema, the description is largely complete: it states the action, the purpose, and the exact trigger condition. The only minor gap is the lack of any detail about the response or what happens if the document is already published, but this does not hinder correct invocation.

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

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

The input schema already documents document_id with 100% coverage, including its type and description. The tool description does not add any additional meaning or constraints beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('publish') and resource ('IT Glue document'), and clarifies the purpose: making section changes visible. This clearly distinguishes it from the sibling section mutation tools like create_document_section, update_document_section, and 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 explicitly says when to call this tool: 'Always call this after creating, updating, or deleting sections.' That is clear and actionable context. It does not mention when not to use it or name alternatives, but the usage condition is specific 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?

With no annotations, the description must carry the behavioral disclosure burden, but it only states the action. It does not mention whether results are paginated, read-only, how sorting/filtering behave, or what the response looks like.

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?

A single, direct sentence with no filler or redundant content. It is appropriately concise and front-loads the key action and resource.

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

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

The description is minimal for a tool with 10 parameters, no annotations, and no output schema. It does not explain the result type, pagination behavior, or how this search relates to get_configuration, leaving meaningful gaps for an agent.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description adds only a slight semantic gloss ('devices/assets') but does not need to restate 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 uses the specific verb 'Search' with the resource 'configurations (devices/assets)' in IT Glue, making the core purpose clear. It does not explicitly contrast itself with the sibling get_configuration, but the search-vs-get distinction is strong enough to differentiate.

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 given on when to use this tool versus alternatives like get_configuration or other search tools. The usage context is only implied by the name and description.

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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It discloses the most important trait — returns metadata only, not the document body — plus the organization scoping constraint. It does not describe edge cases like empty results or auth requirements, but it does not mislead and covers the behavior an agent most needs to avoid wrong expectations.

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 zero filler: the first establishes purpose and scope, the second clarifies the return contract and routes to siblings. 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?

No output schema exists, but the description compensates by enumerating the returned metadata fields and routing content-reads to get_dument and list_document_sections. The 6-parameter surface is fully covered by the schema. Minor gaps remain around ordering, empty -result behavior, and error conditions, but nothing critical for selecting and invoking the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all 6 parameters. The description adds minimal semantic value beyond reinforcing organization scoping and previewing the returned metadata fields (name, folder, URL, timestamps). Per the baseline for high coverage, a 3 is correct.

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 (search), resource (documents), and scope (scoped to an organization), and clarifies the return contract (metadata only, not the body). This distinguishes it from sibling search_* tools on other resource types and from get_document/list_document_sections without requiring the agent to open any 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?

Explicitly tells the agent when to use this tool (metadata search) versus alternatives: 'Use get_document or list_document_sections to read a specific document's content.' The exclusion is direct and names the alternative tools, leaving nothing to inference.

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?

No annotations are present, so the description must carry behavioral disclosure. It only restates the required filter, which the schema already marks as required, and does not address pagination behavior, permission requirements, error semantics, or response format.

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 wasted words. The parenthetical requirement is efficient and easy to parse.

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

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

The description is adequate for a straightforward search tool: the purpose and mandatory filter are stated, and the schema covers parameter details. It is thin on surrounding workflow context such as how to obtain the type ID or what the response looks like, but it is not dangerously incomplete.

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 includes descriptions for all six parameters, so parameter semantics are mostly covered by the schema. The description adds little param-level meaning beyond restating the required filter.

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 that the tool searches flexible assets in IT Glue, naming the verb and resource clearly. It also flags the required filter, distinguishing it from sibling tools like list_flexible_asset_types, which lists types rather than assets.

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

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

The required flexible_asset_type_id gives a clear precondition for using the tool. However, it does not explicitly state when to prefer this tool over related tools or what conditions would make it inappropriate.

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?

With no annotations provided, the description carries the full burden. It discloses that each result includes address fields and phone number and clarifies the entity type, which is useful. However, it does not mention pagination behavior, sorting defaults, or that no filters return all locations, leaving some behavioral gaps.

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

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

The description is two sentences with no redundancy. It opens with the action and resource, states output characteristics, and then provides a usage directive, all in a compact and logical structure.

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 search tool with no output schema, the description partially explains return contents (address fields and phone number) and gives entity-type context. It does not describe the overall response shape or pagination metadata, but the schema's page_size and page_number parameters make pagination inferable, so the description is largely 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 already documents all nine parameters with descriptions. The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches for physical addresses/sites of an organization, with the specific verb 'Search' and resource 'locations'. It also distinguishes locations from flexible assets, making its purpose distinct from sibling search_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?

The description explicitly tells the agent to use this tool rather than search_flexible_assets when looking up an organization's address or phone, providing a clear routing rule. It also explains that locations are a built-in entity, giving context for when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Search' implies a read operation, but the description does not state whether results are paginated, how sorting works, whether filters are exact or partial, or what the response shape is. It adds no behavioral context beyond the tool name.

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 redundancy. It is appropriately concise, though it skips details that would make it more useful for a 7-parameter search 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?

There is no output schema, and the description does not explain return values, pagination behavior, or sorting semantics. With 7 parameters and no annotations, the minimal description leaves significant gaps for an agent deciding how to invoke and interpret the 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 description coverage is 100%, so the schema fully documents all seven parameters. The description's 'optional filtering' adds no meaning beyond the schema, matching the baseline of 3.

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

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

The description states a specific verb ('Search') and resource ('organizations in IT Glue'), and mentions optional filtering. It is clear, but it does not distinguish this from sibling tools like get_organization or search_configurations beyond the resource name.

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: use this when searching for organizations with optional filters. However, it gives no explicit guidance on when to prefer get_organization instead, nor does it mention alternatives or exclusions, so the guidance is only implicit.

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?

With no annotations provided, the description carries the full burden and does disclose a key behavioral trait: it returns metadata only, not actual passwords. This is valuable and prevents an agent from expecting secrets. It does not mention auth, rate limits, or pagination behavior, but for a search tool the metadata-only disclosure is the most important behavior and is clearly stated.

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 filler. The core purpose appears first, and the critical boundary about metadata-only results is placed in a parenthetical that 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?

The tool has 8 optional parameters, no required parameters, a complete schema, and no output schema. The description clarifies what the return type is not (actual passwords) and that it is metadata only, which is sufficient for an agent to know what to expect. It does not detail which metadata fields are returned, but that is a minor gap given the lack of an output schema.

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

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

The schema description coverage is 100%, so all 8 optional parameters are already documented structurally. The description adds no parameter-specific meaning beyond what the schema provides, which is acceptable but does not elevate the score 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 uses a specific verb ('Search'), identifies the resource ('password entries in IT Glue'), and adds a clear distinguishing boundary ('returns metadata only, not actual passwords'). This separates it from siblings like get_password, which likely handles password retrieval.

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 this tool is for searching/finding password entries and for metadata-only needs, but it does not explicitly state when to use it over alternatives or name a sibling tool such as get_password. The 'not actual passwords' note is an implicit exclusion rather than explicit usage guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses key constraints beyond the schema: the date range may span at most 7 days, and end_date requires start_date because IT Glue rejects an open start. It also explains the nature of the returned data (counts, date-bucketed) and its relationship to reputation scores. It does not mention auth requirements or rate limits, but for a search tool this is sufficient.

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

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

The description is three sentences with no fluff. The main action is front-loaded, the resource scope is explained immediately, and the critical constraints are stated last yet clearly. Every sentence contributes either to what the tool does, what the data represents, or how to constrain the call.

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 8-parameter schema, 100% parameter coverage, and absence of an output schema and annotations, the description does a strong job. It explains return data structure, date restrictions, and the tool's purpose. Minor gaps remain, such as the precise response shape and default behavior when no filters are applied, but the description is complete enough for safe invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by linking parameters to the data model: per-user, per-organization, per-resource-type counts directly maps to user_id, organization_id, and resource_type. It also clarifies the relationship between start_date and end_date, which is not obvious from the schema alone. This pushes it 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 and resource: "Search IT Glue user activity metrics." It then details exactly what is returned—per-user, per-organization, per-resource-type counts of actions bucketed by date—and adds context about being the raw data behind reputation scores. This clearly distinguishes it from sibling search tools that target organizations, configurations, locations, passwords, or documents.

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

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

The description provides clear context for when to use this tool: whenever user activity metrics are needed, and it explicitly frames the data as raw reputation-scores input. It does not name alternatives or exclusions, but the domain is so distinct from all sibling tools (which search entities, not metrics) that an agent can confidently select it. The lack of explicit 'when-not-to-use' guidance prevents a 5.

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?

It adds important behavioral context beyond the annotations by warning that this is HIGH-IMPACT, that the document becomes visible to all users, and that confirmation should be requested. This supplements the destructiveHint annotation.

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

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

Two sentences with no wasted words. The high-impact warning is front-loaded, followed by the effect and the required confirmation step.

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-parameter action tool with no output schema, the description is complete. It explains what happens, why it matters, and what the agent should do before invoking.

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

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

The schema description already fully documents document_id as 'The document ID to unarchive' (100% coverage). The description adds no additional parameter-level meaning, so it meets the 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 states a specific verb ('Restores'), the resource ('previously archived IT Glue document'), and the outcome ('appears in normal views again'). This clearly distinguishes it from archive_document and other document operations.

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 clearly indicates when to use it: when a previously archived document needs to be restored. It does not explicitly specify when not to use it or name an alternative, but the context is unambiguous.

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?

No annotations are provided, so the description carries the behavioral burden. It communicates that the tool edits existing sections and that publishing is needed afterward, which is useful. However, it does not disclose permissions, overwrite behavior, or what response to expect, leaving some behavioral uncertainty for a mutation tool.

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

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

Two short sentences with no filler. The primary action is front-loaded, followed by essential workflow instructions. 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?

For a simple 3-parameter mutation with no output schema, the description is fairly complete: it names the resource, explains how to obtain section IDs, and provides the necessary follow-up publish step. It does not mention response format or error conditions, but the core invocation path is well covered.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters. The description reinforces that section_id comes from list_document_sections, but this is also already stated in the schema. It adds no significant semantic value beyond the structured fields.

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 a specific action and resource: 'Update the content of an existing IT Glue document section.' This clearly distinguishes it from siblings like create_document_section and delete_document_section, so an agent can identify the right tool without opening schemas.

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 actionable workflow context: 'Use list_document_sections to get section IDs' and 'Call publish_document after editing.' This is clear usage guidance, though it does not explicitly state when to prefer this tool over create_document_section or delete_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?

With no annotations, the description carries the behavioral disclosure burden. It usefully discloses partial-update semantics ('Only the fields you supply are changed'), but it does not mention permissions, failure modes, idempotency, or what the response contains.

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 short, front-loaded sentences with no filler. The first identifies the action and resource, the second conveys the most important behavioral nuance.

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 13-parameter mutation tool with no annotations and no output schema, the description is functional but minimal. It covers the core partial-update behavior but leaves out use conditions, return values, and error semantics; the schema compensates for parameter documentation.

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 every parameter. The description adds no per-parameter detail, but the partial-update note clarifies that omitted fields retain their existing values, which is relevant for how parameters behave.

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 a specific action ('Update') and resource ('an existing location in IT Glue'), making the tool's purpose immediately clear. The phrase 'existing' also differentiates it from create_location, a direct 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 implies the tool should be used when an existing location needs modification, but it does not explicitly state when to use it over alternatives like create_location or get_location. No exclusions or alternative tool names are given.

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