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

The description goes beyond the annotations by explaining the soft-delete behavior (hides from normal views but is recoverable), and it warns of high impact and the need for user confirmation. This provides meaningful context that annotations alone (destructiveHint, idempotentHint) do not convey, without contradicting 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 concise and front-loaded with a warning symbol and 'HIGH-IMPACT' label, immediately indicating criticality. The three sentences earn their place: warning, action, restoration path, and confirmation instruction. 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?

The tool is simple with one parameter and no output schema, so the description carries the full burden. It covers the action, effects, reversibility, and usage instruction, making it complete for an agent to select and invoke the tool safely.

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 covers the only parameter (document_id) at 100%, so the schema already provides full meaning. The description does not add additional context about the parameter, but this is unnecessary for a simple single-parameter tool. Baseline 3 is appropriate.

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

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

The description clearly states the tool archives an IT Glue document, providing specific details about the soft-delete behavior and recoverability. It distinguishes itself from the sibling tool unarchive_document by explicitly naming it as the restore 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 tells the user to confirm before invoking, indicating it is a high-impact action. It also names unarchive_document as the tool to restore, providing clear guidance on when to use the alternative. However, it doesn't explicitly contrast with other tools like delete_document or hard-delete scenarios.

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

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

Annotations already establish that the tool is not read-only, not idempotent, and not destructive. The description adds the base64 prefix constraint and clarifies that the result is a downloadable attachment, but it does not disclose side effects, permissions, or failure modes. The behavioral disclosure is adequate but not extensive.

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 core purpose and sibling differentiation, then adds the essential encoding requirement in a compact way.

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 tool with no output schema, the description covers the core purpose, the key alternative, and the critical base64 input constraint. It does not explain response format or edge cases, but the schema fully documents the required parameters, so an agent can invoke 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 all four parameters are well documented in the schema already. The description reinforces the 'no data: prefix' requirement, but that same instruction is already present in the content parameter's schema description. The added value over the schema is minimal.

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: 'Attach a file to an IT Glue record.' It also explicitly distinguishes this tool from create_document_image, which is an important sibling. An agent can immediately understand what the tool does and how it is different.

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 closest alternative, create_document_image, and explains the deciding difference: downloadable attachment versus an image in the document body. This gives clear routing guidance and leaves little ambiguity about when to use this tool.

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

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

With no annotations, the description carries the full transparency burden. It discloses non-obvious interactive behavior (folder prompting), the API-key/JWT fallback order, and the accepted prompt inputs (URLs or numeric folder IDs). This is genuinely informative and goes far beyond a trivial 'create a document' statement.

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?

Although the description is longer than typical, every sentence earns its place by explaining a distinct behavioral aspect. The main purpose is front-loaded, and the remaining details are logically ordered from prompt behavior to enumeration fallback to the skip option.

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 and lack of output schema, the description thoroughly covers the most import invocation risks: folder selection, prompt fallback, and the skip flag. It doesn't explicitly state the return format or required auth scopes, but the API key/JWT fallback is already described, and these omissions don't significantly hinder correct use.

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 with 100% coverage, setting a baseline of 3. The description adds meaningful semantics for document_folder_id and skip_folder_prompt by explaining their interaction and the root-creation behavior, which exceeds 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 uses a specific verb and resource: 'Create a new document in IT Glue for an organization.' This clearly distinguishes it from sibling tools like create_document_section or archive_document, and the organization scope is 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?

The description gives clear contextual guidance on when the folder prompt appears and when to use skip_folder_prompt=true. It doesn't explicitly name alternative tools for when-not conditions, but the first sentence clearly establishes the create-document use case relative to 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 annotations already convey that this is a mutating, non-idempotent operation. The description adds valuable behavioral context beyond those annotations: the base64 format requirement, the fact that data: URIs will be rejected, and the need to publish the document afterward. It does not discuss failure modes, rate limits, or what exactly is returned, but with annotations covering the basic safety profile this is reasonably 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?

Three sentences with no filler: the action and purpose, the payload encoding rule, and the critical constraints plus follow-up step. The most important constraint is front-loaded, and 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 three-parameter upload tool with no output schema, the description covers the core workflow, necessary format, and the required follow-up publish action. It is slightly incomplete in that it does not mention how a caller should reference the returned image identifier when building the document section, and it does not explicitly contrast with the sibling create_attachment 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%, and the schema already documents all three parameters, including the requirement to strip any data: prefix from content. The description reinforces that instruction and explains why, but it does not add new parameter-level semantics beyond what the schema already provides. This meets the high-coverage baseline at 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 opens with a specific action ('Upload an image into an IT Glue document') and the intent ('so it can be shown inline in the document body'), making the tool's purpose unmistakable. It also distinguishes it fromsiblings like create_attachment by emphasizing inline use in the document body rather than a generic file 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 gives clear contextual guidance: it explains that the HTML sanitiser rejects inline SVG and data: URIs, so uploading first is explicitly called 'the only way to get a picture into a document body.' It also directs the agent to call publish_document after editing sections. It does not explicitly name create_attachment as the alternative for non-inline attachments, so it stops short of full alternative routing.

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. It adds the key detail that publishing is required after editing, implying changes are not visible until then. But it omits other behavioral traits such as whether the section is appended, what the return value is, and any permission requirements.

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

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

Three short sentences, no filler. The core action, type constraints, and required follow-up are all conveyed in about 25 words.

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

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

The description covers the main operation and the publish dependency, but with no output schema it does not explain the return value. It also omits prerequisites (e.g., document must exist) and insertion behavior, leaving moderate gaps for a 3-parameter creation tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates the enum mapping for section_type (heading to Document::Heading, text to Document::Text) but adds little beyond the schema, which already describes content as HTML and provides the same enum explanation.

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: 'Add a new section to an IT Glue document,' clearly identifying the resource and operation. It also names the two section types, distinguishing this tool from siblings like update_document_section, delete_document_section, and list_document_sections.

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

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

It clearly states when to use the tool (when creating a new section) and provides a critical follow-up instruction ('Call publish_document after editing'). However, it does not explicitly name alternatives or state when not to use it, relying on sibling tool names for that distinction.

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 must carry the behavioral burden. It adds useful context that IT Glue typically requires a country_id even though it is optional in the schema. However, it does not disclose side effects, return value, or failure modes for a write operation, so transparency is 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 sentences with no filler. The first sentence states the action and scope, the second highlights a key requirement. Every word earns its place, and it is front-loaded with the core purpose.

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

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

For a tool with 12 parameters, no output schema, and no annotations, the description is functional but lean. It covers the core purpose and one gotcha, but lacks information about return values, error conditions, or how to choose this over sibling create/update tools. It is minimally 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?

The input schema already has 100% description coverage for all 12 parameters. The description only reiterates that name and country_id are important, which is already captured in the schema's required list and the country_id property description. No additional parameter semantics are provided 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's function with a specific verb+resource: 'Create a new location (physical address/site) for an organization in IT Glue.' This distinguishes it from sibling tools like update_location, search_locations, and get_location, and it also clarifies the scope (for an 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 implies when to use this tool (when creating a new location) by using the verb 'Create' and adding requirements ('requires a name and typically a country_id'). It does not explicitly mention alternatives or when not to use it, but the purpose is unambiguous enough that an agent would not confuse it with update or search 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?

Adds significant context beyond annotations: emphasizes irreversibility, need for user confirmation, and follow-up action. No contradiction with annotations, which already indicate destructive 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 plus a warning symbol. Front-loaded with critical information. Every sentence earns its place – warning, action, follow-up, user confirmation.

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 destructive tool with two parameters and no output schema, the description fully covers purpose, irreversibility, required post-action, and user instruction. No gaps.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds no extra meaning beyond the schema, meeting the baseline expectation.

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

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

The description clearly states the tool deletes a section from an IT Glue document, using specific verb 'Permanently deletes' and resource 'section'. It distinguishes from sibling tools like create_document_section or update_document_section.

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

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

Explicitly instructs to call publish_document after editing and to confirm with the user before invoking, providing clear when-to and when-not-to guidance.

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

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

No annotations are provided, so the description carries the burden. It implies a read-only operation via 'Get' but does not explicitly state safety, error handling, or authentication requirements. For a simple read, this is adequate but could be more explicit.

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 the 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 one-parameter get operation without output schema, the description provides the essential information. However, it could briefly mention what is returned or that the operation is read-only. Overall, it is sufficient but not enriched.

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 only parameter 'id' is fully described in the schema with 'The configuration ID'. The description's 'by ID' adds no additional meaning beyond the schema. Since schema coverage is 100%, 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 action (Get) and the resource (configuration/device/asset by ID), distinguishing it from search_configurations which is for searching. It is specific and unambiguous.

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

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

No guidance is provided on when to use this tool vs. alternatives like search_configurations. There is no mention of prerequisites or contexts.

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. It only states the operation and target, without explaining what happens on not-found, authorization requirements, or the structure of the returned data. This is a minimal but not transparent behavioral description.

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, short, front-loaded sentence with zero redundancy. Every word contributes meaning, and it is immediately scannable.

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?

While the tool is simple and the schema covers parameters, there is no output schema and no description of the return value. For a get-by-ID operation, it is somewhat expected to return the document object, but the description does not confirm this or mention any edge cases, leaving some contextual gaps.

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

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

The input schema already provides 100% coverage with descriptions for both id and organization_id. The description adds no additional parameter semantics, so the baseline 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?

Clearly states the verb 'Get' and the resource 'document' with the specific scope 'by ID from IT Glue'. It is distinct from sibling tools like search_documents, which find documents by query rather than by known 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 phrase 'by ID' implies that this tool is to be used when the document ID is already known, which is a clear usage context. It does not explicitly mention alternatives, but the sibling tool names (e.g., search_documents) make the distinction apparent.

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 clearly indicates a read operation via 'Get' and mentions return content, but it does not disclose additional behavioral traits such as authorization requirements, error handling, or side effects. For a simple retrieval, this is minimally acceptable.

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 front-loads the action ('Get'), resource ('location'), and scope ('by ID') without any filler. It is concise and well-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?

The tool is simple with only one parameter and no output schema. The description states what it retrieves and highlights key returned fields (address, phone number), which is sufficient for a basic get operation. It lacks mention of edge cases like not found, but that's not essential here.

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 has 100% coverage for the single parameter 'id' with a clear description. The tool description adds no extra meaning beyond 'by ID', which is already implied. The description does not compensate for missing schema info because there is no missing info.

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 'Get', identifies the resource 'location' from IT Glue, and specifies the scope 'by ID' along with key return fields ('full address and phone number'). This clearly distinguishes it from sibling tools like search_locations, which is for searching.

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 that this tool is for retrieving a single location when you have its ID, but it does not explicitly mention when to use it versus search_locations or other alternatives. There is no explicit 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?

With no annotations, the description carries the burden of disclosing behavior. The verb 'Get' implies a read-only operation, but no explicit statement about side effects, error behavior, or authentication requirements is given. The description is accurate but minimal, similar to a basic getter.

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 and contains no redundant information. It is appropriately sized for a simple getter tool with one parameter.

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

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

For a simple read tool with one parameter and no output schema, the description is sufficiently complete. It states the operation and source, though it could be enhanced by noting that it returns a single organization or by referencing search for finding IDs, but that is arguably unnecessary.

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% coverage for the single parameter 'id' with description 'The organization ID'. The tool description adds no additional meaning beyond the schema, 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?

The description clearly uses the verb 'Get' with a specific resource ('specific organization by ID') and the source system ('IT Glue'). It distinguishes from the sibling 'search_organizations' by focusing on retrieval by ID rather than 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 on when to use this tool versus alternatives like 'search_organizations'. The description simply states the function without context or exclusions, leaving the agent to infer usage purely from the required 'id' parameter.

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 explicitly discloses that the response includes the actual password value, which is a key behavioral trait about sensitive data exposure. However, it does not mention permissions, side effects, or that the value can be suppressed via show_password.

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, front-loaded with the core action and resource. No redundant information or filler words.

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

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

Given the simple tool (2 parameters, no output schema), the description adequately conveys the tool's function and key behavior. It could mention the default of show_password, but the schema covers that, so completeness is high for the complexity level.

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 show_password clearly documented in the input schema. The description adds little beyond the schema, but it aligns with the show_password behavior by noting the inclusion of the password value. No additional parameter meaning is needed.

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 password entry by ID from IT Glue, using the verb 'Get' with a specific resource. It distinguishes from sibling tools like search_passwords by emphasizing ID-based retrieval rather than 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?

Usage is implied: you use this when you have a password entry ID. However, it does not explicitly mention alternatives like search_passwords for finding IDs, nor exclude cases where the ID is unknown.

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. It indicates a read-only operation ('check connectivity') but does not explicitly state non-destructiveness, return format, or error behavior. It adds some context by specifying the mechanism (fetching organization types), but lacks a full behavioral disclosure.

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 unnecessary words. It effectively communicates the tool's purpose without padding.

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?

Since there is no output schema, the description should explain what the tool returns or how connectivity is indicated. It merely states the action and mechanism, leaving the user to infer the result. This is incomplete for a simple health-check tool.

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

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

The tool has zero parameters, so the schema is trivially complete. The baseline for 0 params is 4; the description doesn't need to add parameter information, and it doesn't.

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 'Check connectivity' and identifies the resource (IT Glue API) and method (fetching organization types). It clearly distinguishes this tool from all sibling tools, none of which are health checks.

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 verifying API connectivity but does not explicitly state when to use it versus alternatives or provide exclusions. Since the tool is unique among siblings, the implied usage is clear, but no explicit 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?

There are no annotations, so the description carries the full burden. It discloses the read-only listing behavior and that download URLs are returned, but it does not mention authentication requirements, pagination, or what metadata is included for each attachment. Some behavioral context is present, but not deeply.

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 concise sentence that states exactly what the tool does and what the response will include. Every word earns its place, and there is no redundant or filler 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 list operation with two fully documented required parameters, the description is sufficient to understand what the tool returns and how to invoke it. Without an output schema, mentioning download URLs helps, though additional details about the response shape would strengthen 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 resource_type and resource_id are already well documented. The description only adds 'IT Glue record' context and does not meaningfully extend parameter semantics, which is acceptable because the schema covers them.

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

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

The description uses a specific verb ('List'), names the resource ('files attached to an IT Glue record'), and adds the valuable detail that download URLs are included. This clearly distinguishes it from sibling tools like create_attachment or 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 description gives clear context: use this when you need to list files attached to a record. It does not explicitly mention alternatives or when-not-to-use scenarios, but the read-only list behavior is obvious and unambiguous relative to the sibling tool set.

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 provided, but description compensates by disclosing return values, API key/JWT fallback auth flow, and tenant rollout status. Does not mention pagination behavior, but schema documents page parameters.

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, front-loaded with purpose, then efficient auth/availability context. Every clause earns its place with no 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?

Covers purpose, return values, auth fallback, and availability. Lacks explicit pagination behavior, but that is partially covered by schema parameters. Sufficient for a simple 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 description coverage is 100%, so baseline is 3. Description doesn't add parameter-specific semantics beyond the schema, which already documents all four parameters clearly.

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 action ('List'), resource ('document folders'), scope ('for an organization'), and return value ('names and IDs'). Clearly distinguishes from sibling tools like list_document_sections.

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

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

Provides clear context for when to use (`list document folders for an organization`), plus availability constraints (tenant rollout). Lacks explicit alternatives or exclusions, but the resource is distinct enough from siblings that this is sufficient.

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

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

No annotations are present, so the description must carry behavioral disclosures. It adds two useful behaviors: output is ordered, and the operation is read-only (implied by 'read document content'). However, it leaves unclear whether sections include full content, pagination limits, or permissions required.

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, both essential. The first states the action; the second gives the use case. 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 single-parameter list tool, the description adequately covers purpose and intended usage. Since there is no output schema, a brief note on what is returned (section details) would improve completeness, but the current description is sufficient for basic 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 schema already documents the sole parameter (document_id) with 100% coverage. The description adds no additional parameter semantics, 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?

The description clearly states the function with a specific verb ('List'), resource ('sections of an IT Glue document'), and scope ('all' and 'in order'). It also positions the tool relative to editing workflows, distinguishing it from document-level or folder-level 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 instruction 'Use this to read document content before editing' provides explicit guidance on when to invoke the tool. It does not enumerate alternatives or exclusions, but for a simple list operation this is sufficient 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?

No annotations, but description implies a safe read operation and explains the optional filtering behavior (returns global types if omitted). Lacks details on return format but sufficient for a simple list.

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 unnecessary information. Front-loaded with the action and followed by usage 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?

Given the simple one-parameter tool and no output schema, the description covers what the tool does, when to use it, and the parameter behavior. It implies the return includes type IDs, which is sufficient for 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 coverage is 100%, so baseline is 3. The description does not add new meaning beyond the schema's parameter description, which already explains the optional filter and default behavior.

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 flexible asset types and distinguishes it from the sibling search_flexible_assets by specifying it's for discovering type IDs before searching.

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 to call this first before using search_flexible_assets, providing clear sequential guidance and context for when to 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?

With no annotations provided, the description bears the burden of disclosing behavior. It clearly explains the behavioral effect ('make section changes visible') and implies that section changes are not visible until publishing. This is adequate for a simple publish operation, though it omits details like idempotency or error 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 two sentences long, front-loads the purpose, and immediately provides the critical usage guidance. Every sentence adds value with no wasted words.

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

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

For a tool with one simple parameter and no output schema, the description provides sufficient context: what it does, when to call it, and the intended effect. It fits well within the sibling toolset as the necessary follow-up after section modifications.

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% coverage for the single parameter 'document_id' with a clear description ('The document ID to publish'). The tool description adds no additional parameter semantics, 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 ('Publish') on an IT Glue document with a clear purpose ('make section changes visible'). It is distinct from sibling tools like create_document_section or archive_document, as none of them perform the publish action.

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

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

The description explicitly states when to use the tool: 'Always call this after creating, updating, or deleting sections.' This provides clear context for usage, though it does not mention alternatives or when not to use it, stopping short of the 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?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states 'Search for configurations' without mentioning pagination, sorting, filtering behavior, return format, or any rate limits. The schema hints at pagination via page_size/page_number, but the description itself does not explain these behaviors.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the key action and resource, making it immediately clear what the tool does.

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 10 parameters, no annotations, and no output schema, but the description does not explain the return value format or overall behavior. It does not mention that results are paginated or that multiple filters can be combined. The schema provides parameter details, but the description fails to give a complete picture of the tool's capabilities and outputs.

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 every parameter having a clear description. The tool description adds only a minor clarification that configurations are devices/assets, but does not supplement any parameter-specific information. Thus, it meets the baseline for parameter semantics without adding significant value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Search for configurations (devices/assets) in IT Glue'. It uses a specific verb ('Search') and resource ('configurations'), and clarifies that configurations refer to devices/assets. This distinguishes it from sibling tools like get_configuration, which implies retrieving a single item, and search_organizations, which targets a different resource.

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, nor does it mention any prerequisites or exclusions. While the verb 'Search' implies usage for listing/filtering versus retrieving a specific configuration, there is no explicit comparison to get_configuration or other search 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?

With no annotations, the description carries the burden of behavioral disclosure. It explicitly states the tool returns metadata only, not the document body, which is a critical behavioral trait. It doesn't mention pagination or sorting behavior, but those are evident from the schema; the key usage constraint is well communicated.

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, immediately stating the purpose, followed by crucial output limitations and alternative tool guidance. No wasted words; every sentence earns its place.

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

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

Despite no output schema, the description names the returned metadata fields (name, folder, URL, timestamps) and guides the agent to content-reading tools. Pagination and sort details are in the schema, so the description is reasonably complete for a search 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 baseline is 3. The description reinforces that organization_id is required ('scoped to an organization') but does not add additional parameter-level meaning beyond what the schema already 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 a specific verb ('Search') with a clear resource ('documents') and scope ('scoped to an organization'). It also distinguishes from siblings by stating it returns metadata only and explicitly pointing to get_document and list_document_sections for content.

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

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

Provides explicit alternatives: 'Use get_document or list_document_sections to read a specific document's content.' This clearly tells the agent when not to use this tool (when full content is needed), satisfying the usage guidance dimension.

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 transparency burden. It implies a read-only operation through 'search' and states a necessary precondition, but it does not disclose pagination behavior, result format, or any other side effects. This is acceptable but thin for a tool with no 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 a single front-loaded sentence that communicates the core action and its essential constraint. There is no wasted text or unnecessary repetition.

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 search tool with well-documented schema parameters, the description is largely complete: it names the resource, the operation, and the critical requirement. It does not explain return values, but that is easily inferred from a 'search' action and is not essential given the simplicity.

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% as all parameters have descriptions. The description only reinforces the required flexible_asset_type_id parameter, adding no extra semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Search for flexible assets in IT Glue'. The parenthetical requirement of flexible_asset_type_id differentiates it from other search tools for different resource types.

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

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

It explicitly notes the required filter ('requires flexible_asset_type_id filter'), which is an important usage condition. It does not explicitly mention alternatives, but the resource type in the description makes it clear when to choose this tool over sibling search 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?

With no annotations, the description carries the burden and reveals the result contents (address fields and phone number) and clarifies the entity type. It could mention pagination defaults or sort behavior, but those are covered in the schema, so this 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 sentences that are efficiently front-loaded with the purpose and a sibling distinction. Every sentence adds value, with no redundant or vague wording.

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 9 parameters and no output schema, the description covers key contextual aspects: result fields, entity type, and how it differs from flexible assets. It could elaborate on pagination behavior, but the schema describes page size and page number, making this reasonably 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% with descriptions for all 9 parameters, so the schema does the heavy lifting. The description only adds context about result fields, not additional parameter semantics, meriting the baseline 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?

States 'Search for locations (physical addresses/sites) of an organization' with a specific verb and resource, and clearly distinguishes itself from search_flexible_assets by noting locations are a built-in entity.

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

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

Explicitly says 'use this rather than search_flexible_assets to look up an organization's address or phone', providing a clear when-not and an alternative. This gives concrete guidance on when to choose this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'search for organizations,' omitting key behavioral traits like returning a paginated list, supporting sorting, or being read-only. No mention of what the response contains, rate limits, or other side effects. This is almost a tautology of 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, concise sentence with no wasted words, front-loaded with the verb 'Search.' It is appropriately sized for a simple purpose but lacks additional structure or 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 no output schema and no annotations, the description should explain return values, pagination, or typical usage context. It only states the search action and optional filtering, leaving out crucial details for a tool with multiple filters and pagination parameters. The description is insufficiently complete for an agent to invoke it confidently.

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% coverage with each parameter described (e.g., 'Filter by organization name (partial match)'). The description adds no additional parameter meaning beyond the generic 'optional filtering,' so the baseline of 3 applies. It does not compensate or contradict 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 searches for organizations in IT Glue, using a specific verb and resource. It distinguishes from sibling tools like search_configurations or search_passwords by naming the resource explicitly. However, it lacks specific scope details such as 'with optional filtering by name or ID' that would make it fully unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like get_organization or other search tools. The phrase 'with optional filtering' implies usage for lookup but does not state exclusions or alternate tools. Since sibling tools are available, the description should have noted when to use search versus direct retrieval.

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

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

With no annotations provided, the description carries the full burden. It discloses a critical behavioral trait: the tool returns metadata only and never actual passwords. This is essential for managing user expectations and security. It does not mention other behaviors like pagination or read-only nature, but the key risk is covered.

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, then immediately clarifies the key limitation. No filler or redundant information.

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

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

The tool has 8 optional parameters, no output schema, and no annotations. The description clarifies the core purpose and the fact that only metadata is returned, but does not describe what metadata fields are included or how results are structured. This is a gap, though the schema covers filtering options.

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

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

The input schema has 100% coverage with descriptions for all 8 parameters, so the description does not need to explain parameters. The description adds no parameter-specific value beyond what the schema already provides, but the schema is self-sufficient.

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 'Search' and the resource 'password entries in IT Glue', making the purpose unambiguous. It also differentiates from sibling tools like get_password by noting it returns metadata only, not actual passwords.

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 this tool vs alternatives by explicitly stating it returns metadata only, not passwords. This suggests that if actual passwords are needed, another tool (such as get_password) should be used. However, it does not explicitly name the alternative tool, so the guidance is somewhat 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?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral constraint (date range max 7 days, end_date requires start_date, IT Glue rejects open start) and explains what the data represents. However, it doesn't mention read-only safety, auth requirements, or potential rate limits. For a search tool, these missing traits are less critical, but the lack of any explicit safety statement prevents a higher score.

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 primary purpose, then adding essential constraints. Every word earns its place, with no repetition of schema details or fluff. The structure is highly efficient and scannable.

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 no output schema, the description adequately explains the return value concept (counts grouped by user, organization, resource type, and date bucket). It also covers the critical date constraint. It doesn't detail response formatting or pagination structure, but for a search metrics tool, the provided information is sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explicitly stating that end_date requires a start_date and that IT Glue rejects an open start, which the schema does not mention. It also clarifies the 'bucketed by date' semantics, giving a better mental model of how start_date/end_date affect output. 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 clearly states a specific verb and resource: 'Search IT Glue user activity metrics' with detailed specification of what is measured (per-user, per-organization, per-resource-type counts of created/viewed/edited/deleted actions, bucketed by date). This distinguishes it from sibling search tools that target different entities like organizations or configurations. The extra context about being raw data behind reputation scores adds distinctive clarity.

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

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

The description provides clear context for when to use this tool: when you need user activity metrics or the raw data behind IT Glue reputation scores. It doesn't explicitly mention alternatives or exclusions, but the purpose is clear enough to imply the appropriate use case. No sibling tool covers the same domain, so the differentiation is inherent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context by emphasizing 'HIGH-IMPACT' and explaining that unarchiving 'makes the document visible to all users,' which is not fully captured by the annotations. It also includes a safety instruction for user confirmation.

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 extremely concise: two short sentences. The warning is front-loaded with '⚠ HIGH-IMPACT,' followed by a clear purpose and a directional usage note. Every sentence earns its place 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?

The tool is simple (one parameter, no output schema, no nested objects). The description covers purpose, impact, and a prerequisite (user confirmation), which is sufficient for an agent to select and invoke the tool correctly. Additional return-value details are unnecessary given the absence of an output schema.

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

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

The schema fully describes the single parameter 'document_id' with a clear description. The tool description does not add further semantic detail about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate given the 100% schema description coverage.

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

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

The description clearly states the action: 'Restores a previously archived IT Glue document' with a specific effect ('appears in normal views again'). It also distinguishes from sibling tools like archive_document by describing the inverse operation, and notes the visibility impact on all users.

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

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

The description provides explicit usage guidance by warning 'HIGH-IMPACT' and instructing to 'Confirm with the user before invoking.' It implies the appropriate context (when a document is archived and needs to be restored) but does not explicitly list alternatives or exclusions; sibling tools make the context clear.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses that the tool mutates an existing section and that changes require a publish step to take effect. It does not mention permissions, return values, or error behavior, but the key workflow implication 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?

Two concise sentences, front-loaded with the purpose, then precise workflow steps. No wasted words or redundancy with schema.

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

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

Tool is simple with three fully described parameters and no output schema. The description provides all necessary context: what it does, how to get IDs, and what to do after. Complete for the tool's complexity.

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 the workflow context that section_id comes from list_document_sections, which reinforces the schema but adds little beyond it. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Update the content') and the resource ('existing IT Glue document section'), using a specific verb+resource format. It is distinguishable from sibling tools like create_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?

Provides explicit workflow guidance: use list_document_sections to get section IDs and call publish_document after editing. This tells the agent when and how to use the tool, including prerequisites and post-conditions.

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. It does add value by explaining the partial-update behavior ('Only the fields you supply are changed'). However, it omits other important behavioral details such as prerequisites (e.g., the location must exist), authorization requirements, or what happens on invalid input, leaving significant 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?

Two sentences, both dense with information. The first sentence gives purpose and scope; the second adds the key partial-update nuance. No wasted words or redundancy.

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

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

The description is adequate for a basic update tool, covering the core action and the partial-update behavior. However, since there is no output schema, the description does not mention what the tool returns (e.g., the updated location object) or error behaviors. For a 13-parameter mutation tool, this is a noticeable 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by explaining that the optional parameters are only modified when supplied, which is essential for understanding update semantics. This goes beyond the per-field descriptions in the schema.

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

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

The description states a clear action ('Update an existing location') and the resource (location in IT Glue). The word 'existing' differentiates it from the sibling create_location, and the verb 'update' is specific and unambiguous.

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

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

The description clearly implies when to use this tool: to modify an existing location, as opposed to creating a new one. The phrase 'Only the fields you supply are changed' provides context for partial updates. However, it does not explicitly name alternatives or exclude cases, so it stops short of full guidance.

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