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

Annotations provide readOnlyHint=false and destructiveHint=true, but the description goes well beyond by clarifying the soft-delete mechanism, note about recoverability, and the high-impact warning. It adds meaningful behavioral context beyond the annotations rather than merely restating 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?

Two tight sentences plus a leading warning label. Every element earns its place — the high-impact warning is front-loaded, the mechanism is stated clearly, and the reversal tool is named. Zero waste.

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

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

For a single-parameter tool with a strong warning, 100% schema coverage, and a clear sibling reference, this description covers the essential context well. The high-impact flag and reversal path are the key completeness elements, both present. Minor gap: doesn't describe return/effects details, but no output schema exists to fill that — though a one-line note on what happens post-archive would add value.

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

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

Schema coverage is 100% and there's only one parameter, so the schema fully documents it. The description doesn't add parameter-specific detail beyond the schema, but given complete schema coverage and a single simple parameter, 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?

Clear verb+resource: 'Archives an IT Glue document'. Explicitly states it's a soft delete that hides from normal views but remains recoverable, fully distinguishing it from sibling tools like delete_document_section or unarchive_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?

Explicitly names the alternative: 'Use unarchive_document to restore', giving the agent clear reversal guidance. Also states 'Confirm with the user before invoking' — a clear before-use prerequisite. Strong when/context guidance for a destructive-ish operation.

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 full burden for behavioral disclosure. It does well by explaining the interactive prompt behavior, the fallback chain for folder enumeration (API key → JWT → URL/ID input), and the skip behavior at the organization root. It could mention create-side effects like whether duplicate names are rejected or whether content is required, but the prompt/picker mechanics are thoroughly disclosed.

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, information-dense paragraph that front-loads the core purpose and then explains the folder selection mechanics. It's slightly verbose in the middle section about folder enumeration fallbacks, but every detail serves the agent's decision-making. Some of the enumeration detail could arguably be trimmed, but it's no waste.

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

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

For a creation tool with 5 parameters (2 required), no output schema, and no annotations, this description is complete. It explains the folder placement decision matrix, the prompt interaction, the root override, and fallback mechanisms. The 100% schema coverage compensates for the missing output schema, and the description's richness covers the interactive/network-dependent behaviors that the schema cannot express.

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 all 5 parameters are documented in the schema. The description adds value by explaining the relationship between document_folder_id and skip_folder_prompt (how they interact), and clarifies that skip_folder_prompt=true means 'organization root.' The schema already details folder ID location hints, so the description's marginal addition is modest but useful.

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 purpose: 'Create a new document in IT Glue for an organization.' It uses a specific verb (create) and resource (document in organization), which is distinct from siblings like create_document_section, publish_document, and archive_document. The description also differentiates from the search/get/read siblings by being the creation tool.

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

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

The description gives excellent when-to-use guidance, explaining the folder-picker flow in detail: when to pass document_folder_id, when to pass skip_folder_prompt=true, and how folder enumeration behaves (API key first, then JWT, then accepting URLs or numeric IDs). It explicitly states the behavior when neither folder parameter is supplied (user prompted), giving clear decision criteria for when to use the root-creation shortcut.

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 that this is a create/mutation operation (implied by 'Add'), and the publish_document follow-up hints at the persistence model (changes aren't live until published). However, it doesn't disclose behavioral details like whether this returns the created section, errors on invalid document_id, or whether it requires specific permissions. With zero annotations, a 3 is reasonable.

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, zero filler. First sentence states the purpose and section types; second sentence gives the critical follow-up workflow instruction. Every word earns its place.

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

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

For a create tool with 3 simple parameters, 100% schema coverage, and no output schema, the description is reasonably complete. The publish_document follow-up handles the key workflow gap. It could note that heading vs text sections have different rendering implications, but that's arguably beyond scope for a concise description.

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

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

Schema description coverage is 100%, meaning all 3 parameters already have descriptions in the JSON schema. The tool description adds the section_type class mappings (Document::Heading / Document::Text) which go slightly beyond the schema, but not substantially. The content parameter's 'HTML content' semantic is already in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb (Add) + resource (section to an IT Glue document) and distinguishes it from siblings (update_document_section, delete_document_section, publish_document). It also specifies the two supported section types with their internal class mappings, which is highly specific and useful.

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 instructs calling publish_document after editing, which is a clear usage guideline. It implies this is an editing workflow step. It does not explicitly say when NOT to use this tool or reference alternatives like update_document_section, but the publish instruction provides important workflow 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 are provided, so the description carries the behavioral disclosure burden. It does reveal a useful behavioral trait (country_id is typically required), which adds value. However, it doesn't disclose what happens on creation (return shape), whether it's idempotent, or whether it can overwrite existing locations. For a mutation tool with zero annotation coverage, there's meaningful detail, but gaps remain about failure modes and return 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 a single, well-formed sentence that packs purpose, resource type, and a practical usage note. Zero wasted words, no redundancy with the schema, and the most important operational detail (country_id requirement) is front-loaded for the agent.

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 12 parameters, no output schema, and no annotations, the description is reasonably complete. It covers the essential action, notes a critical requirement (country_id), and identifies the parent context (organization). The main gap is lack of guidance about what a successful response looks like, but with no output schema present, the agent can infer typical creation semantics. Given the tool's complexity, this is adequate but not exhaustive.

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 12 parameters effectively. The description adds value mainly for country_id (explaining it's typically required and how to find valid IDs) and clarifies the success/failure implication of required params names. This is marginal value beyond what the schema provides, fitting the baseline 3 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 clearly states the verb ('Create') + resource ('location/physical address/site') + target ('for an organization in IT Glue'). It also adds valuable scoping detail that distinguishes it from sibling tools like search_locations, get_location, and update_location — it's specifically for creation, not querying or modification.

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

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

The description clearly indicates when to use this tool (creating a new location) and notes the practical requirement of a name and typically a country_id. However, it doesn't explicitly contrast against siblings like update_location or search_locations, though the create-vs-search distinction is largely implicit. The context is clear but no explicit 'when-not-to-use' guidance is given.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description isn't duplicating that. It adds genuine value by warning 'IRREVERSIBLE', 'cannot be undone', and 'confirm with the user before invoking' — critical behavioral context beyond what annotations state. Also clarifies the post-delete workflow dependency on publish_document.

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?

Description is compact at 3 sentences with a prominent warning prefix. Every sentence earns its place: warnings, action, follow-up, user-confirmation guidance. Slightly verbose phrasing but front-loaded with the most critical info first.

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

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

For a destructive 2-param tool with no output schema, the description covers the key risks (irreversibility), the required follow-up (publish_document), and the confirmation requirement. It lacks detail on what happens to linked resources or dependent content, but for a 2-param delete operation this is 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 both parameters documented. Description adds the provenance note that section_id comes from list_document_sections (in the schema) and mentions publish_document as a follow-up step. The schema handles the parameter semantics well, so the description doesn't need to add much; baseline 3 with slight bump for the workflow context.

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 uses specific verb+resource ('deletes a section from an IT Glue document'), clearly states permanence and irreversible nature, and distinguishes from siblings like update_document_section and create_document_section. Also distinguishes from archive_document (which is reversible).

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. However, it does not specify when not to use it or name alternatives like archive/revert for reversible cases. The 'confirm with the user' guidance is a strong, clear usage directive.

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 of behavioral disclosure. The description doesn't state whether an invalid/nonexistent ID returns an error or null, whether the configuration includes related objects (credentials, documents), or any authentication requirement. For a lookup tool with zero annotation coverage, this is a meaningful gap.

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 waste. It front-loads the core purpose. However, for such a short description, one could argue it under-specifies rather than being optimally concise, though the core content is clearly presented.

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 and no annotations, the description carries the full burden. A single-parameter lookup tool with no return-value description leaves the agent uncertain about what shape the response takes. For a tool with only one parameter and a straightforward purpose, the context is minimal but apparent; however, the absence of any output/return guidance makes it incomplete for a retrieval 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 coverage is 100% with a single 'id' parameter described as 'The configuration ID'. The description adds minimal meaning beyond this, only noting the resource type (device/asset). With high schema coverage, baseline 3 is appropriate; the description doesn't contradict but also adds little 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 configuration (device/asset) by ID from IT Glue' with a clear verb+resource. It identifies the resource as a configuration (device/asset) and the retrieval method (by ID). However, it doesn't distinguish this from search_configurations, a sibling tool that serves a similar lookup purpose, so differentiation is absent.

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. The sibling search_configurations could likely find configurations by criteria other than exact ID, but the description doesn't clarify when get_configuration is preferred over search_configurations or any other 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 burden of behavioral disclosure. The description names the resource and scope (IT Glue) but doesn't describe typical retrieval behaviors like whether it returns the full document content, sections, or just metadata. There's no contradiction with annotations (none exist), but for a read tool it's minimally 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?

Single sentence, 11 words, zero wasted content. It states the verb, the resource, the retrieval key, and the source system. Efficient and front-loaded.

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

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

This is a simple read tool with 2 well-documented parameters and no output schema, so completeness expectations are modest. The description covers purpose and key input. However, it doesn't hint at what the expected return looks like, which an agent might want to know when handling the response.

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' (The document ID) and 'organization_id' (Organization ID that owns the document) explained in the schema. The description adds 'by ID' context that reinforces the 'id' parameter's role, but doesn't explain formatting requirements, how organization_id relates to the document, or what happens if the ID doesn't exist. Baseline 3 is appropriate since the schema already documents both parameters well.

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?

Clear verb+resource: 'Get a specific document by ID from IT Glue' tells the agent this retrieves a single document. It distinguishes from search_documents (which searches) and list tools, though it doesn't explicitly differentiate from siblings like get_configuration or get_organization.

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

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

The description implies usage context through 'by ID' — this is the tool to fetch a single specific document when you know its ID, versus search_documents for finding documents. However, it provides no explicit when-to-use, prerequisites, or guidance versus alternatives like list_document_folders or get_document's sibling retrieval 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?

No annotations are provided, so the description carries full behavioral disclosure burden. It doesn't disclose behavior beyond the basic read operation, such as what fields are returned, whether the full address/phone are always present, error behavior for invalid IDs, or authentication/permission requirements. For a read tool the omission is a moderate gap.

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 concise sentence that front-loads the action and resource, with the address/phone detail adding value without verbosity. Zero 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 single-parameter retrieval tool with 100% schema coverage, the description is mostly adequate. However, with no annotations and no output schema, it could benefit from noting what the response includes, but this is a low-complexity tool (1 param, no nested objects) so the gap is modest.

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% — the single 'id' parameter is already documented as 'The location ID' in the input schema. The description adds 'specific location' context but no additional semantic detail beyond what the schema's own description provides. Baseline 3 applies given full 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?

Clear specific verb+resource: 'Get a specific location by ID from IT Glue, including its full address and phone number.' It distinguishes from siblings like search_locations (which searches) and create_location/update_location. The mention of 'full address and phone number' adds retrieval scope specificity.

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

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

Implied usage is to retrieve a single location by ID as opposed to searching. However, there's no explicit statement of when to choose this over search_locations, or any exclusions or prerequisites noted. Context is inferable but not 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 provided, so the description carries the full burden of behavioral disclosure. It's a read operation (implying non-destructive), but the description doesn't state this explicitly, nor does it mention rate limits, authentication requirements, or what happens if the ID doesn't exist (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?

Single sentence, zero waste, front-loaded with the verb and resource. However, it's arguably under-specified rather than concise; one sentence is appropriate for a simple get-by-id operation, which earns it a 4.

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 single-parameter get-by-ID tool with a clear schema and 100% coverage. The description is adequate for this complexity level. However, with no annotations and no output schema, it could note what fields to expect in the response or behavioral characteristics. For a simple tool, this is reasonably complete but not exceptional.

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% (the single 'id' parameter is documented as 'The organization ID'), so the baseline is 3. The description adds minimal value beyond the schema - it says 'by ID' which reinforces what the schema already states about the id parameter.

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

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

The description clearly states the verb (Get), resource (organization), scope (specific by ID), and data source (IT Glue). It distinguishes from siblings like search_organizations (which searches instead of getting by ID) and search_configurations. Clear purpose but doesn't explicitly note the distinction from the search sibling, so not a 5.

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

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

No guidance on when to use this tool versus search_organizations or other alternatives. The description implies usage (when you have a specific organization ID) but doesn't state exclusions or alternatives. Given the sibling list includes search_organizations, explicit differentiation would help.

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 of behavioral disclosure. It does clarify the key behavioral trait that the response includes the actual password value, which is important context. However, it doesn't disclose whether there are permission requirements for seeing the password value, or what the response format looks like beyond the 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?

Single sentence, zero wasted words. It fronts the core purpose and adds the key behavioral note about including the password value. Nothing extraneous.

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, so the description carries responsibility for explaining return behavior—it mentions the password value inclusion, which is the critical piece. However, for a tool retrieving a sensitive secret, it's missing guidance on the show_password toggle semantics and any authorization caveats. Adequate but not thorough.

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 both parameters (id and show_password) are documented in the schema. The description adds no further semantic detail beyond what the schema provides. Per the rubric, with high schema coverage, baseline 3 is correct since the description doesn't need to compensate.

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') plus resource ('password entry') and adds scope ('by ID') and source ('IT Glue'). It clearly distinguishes from sibling tools like search_passwords (which searches rather than retrieves a specific item). The parenthetical noting it 'includes the actual password value' reinforces what makes this tool distinct.

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 retrieving a specific password by ID, which distinguishes it from search_passwords. However, it does not explicitly state when to use this vs alternatives like search_passwords, nor mention any caveats about sensitivity or permissions for accessing password values. Usage context is only implied, not stated.

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

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

No annotations are provided, so the description carries the burden. The description states that it fetches organization types as a connectivity proxy, which discloses the mechanism. However, it doesn't clarify whether this is a read-only operation, what happens on failure, response format, or whether it creates any side effects. For a health check tool with zero annotations, more behavioral disclosure would help.

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 fully conveys the tool's purpose without any wasted words. It's appropriately short for a zero-parameter health check 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?

For a health check tool with zero parameters and no output schema, the description could specify the expected result (e.g., what a successful check returns, what happens on auth failure). The mechanism (fetching organization types) is stated, but the return/error behavior isn't described. Given the tool's simplicity, this is adequate 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?

The tool has 0 parameters, and schema coverage is 100% (nominal). With no parameters to document, this dimension is trivially satisfied. The description effectively explains what the check does via its mechanism mention, making the parameter dimension a non-issue.

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+resource ('Check connectivity to IT Glue API') and the method ('by fetching organization types'). It distinguishes itself from siblings since it's a health/connectivity check rather than a data operation. However, it could be slightly clearer about whether it's a pure connectivity test or an actual data 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 usage as a connectivity health check, which is clear from the purpose. However, it doesn't explicitly state when to use this vs alternatives (e.g., when to run this before other operations, or whether it should be used as a preflight check). The 'by fetching organization types' hint suggests it validates auth/permissions implicitly, 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?

No annotations are provided, so the description carries the burden. It discloses the auth fallback behavior (JWT fallback via env var/header/prompt) which is useful, and notes the partial rollout. However, it doesn't describe pagination, sorting order, or what happens when there are no folders, leaving some ambiguity for a list operation.

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 core purpose, then expanding into rollout and auth details. The auth fallback explanation is a bit long but genuinely useful. No wasted words in the main purpose statement.

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 filtered-list tool with full schema coverage. The description covers purpose, scope, rollout caveat, and authentication. Missing return-format details and pagination behavior are minor gaps, but the 2026 rollout warning is especially valuable and arguably essential context for this specific 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 schema already documents all 4 parameters. The description adds minimal parameter-level value beyond the schema (authentication context), which aligns with the baseline 3 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 has a specific verb+resource ('List document folders') plus a clear scope ('for an organization in IT Glue') and states the return value ('names and IDs'). It distinguishes itself from siblings like list_document_sections by naming the Document Folders resource explicitly.

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 on when to use it (list folders where IT Glue exposes the resource, noting 2026 rollout) and details about authentication behavior including API key vs JWT fallback. This gives the agent solid guidance on prerequisites and operational 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'List' clearly signals a read-only operation, which is good. However, it doesn't disclose return format, ordering semantics beyond 'in order,' or whether empty documents return nothing. For a read-only listing tool this is acceptable 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?

Two sentences, zero waste. The first sentence states the operation, the second provides usage guidance. Every word earns its place; no filler 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?

For a simple read-only listing tool with a single parameter and full schema coverage, this description is adequately complete. It tells the agent what it does and when to use it. The lack of an output schema is partially compensated by the 'list all sections' framing, though more detail on what section data is returned would strengthen it.

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% — the single parameter document_id is already documented as 'The document ID' in the schema. The description adds no additional parameter semantics beyond what the schema provides, so 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 verb ('List') and resource ('sections of an IT Glue document') with a clear scope ('all sections in order'). It doesn't explicitly distinguish from sibling tools like list_document_folders, but the resource is specific enough that an agent can identify the purpose.

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

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

The description provides clear usage context: 'Use this to read document content before editing.' This tells the agent when to use this tool — specifically as a precursor to editing a document. It doesn't explicitly exclude alternatives, but the workflow guidance is practical and actionable.

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 implies a read-only list operation ('List all') which reasonably signals a non-destructive fetch, and explains the filtering behavior via the parameter schema. However, it doesn't disclose return format, pagination, or the relationship between global and organization-specific results beyond what the schema indicates.

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, zero waste. The first sentence states the purpose, the second provides forward-looking usage guidance. Every word earns its place.

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

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

The tool is simple (no required params, no output schema, no nested objects), so the description covers the core information. It names the downstream tool to use after discovery, which is valuable context. Gaps include no mention of whether results can be large or how to consume type IDs in the downstream call, but these are minor for a discovery 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 parameter is fully documented in the schema (optional organization filter, returns global types if omitted). The description doesn't add meaningful semantics beyond restating the filtering behavior, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists all flexible asset types in IT Glue with a specific verb+resource combination. It distinguishes its purpose from the sibling search_flexible_assets tool by implying it returns type definitions rather than asset records, though it doesn't explicitly name all siblings as alternatives.

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

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

The description explicitly instructs to call this tool first to discover type IDs before using search_flexible_assets, giving clear ordering guidance relative to a named sibling. It doesn't provide when-not-to-use guidance for other potential contexts, but the scoping to a discovery/prerequisite role is helpful.

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 full burden of behavioral disclosure. It states that the tool makes changes visible, but doesn't disclose whether publishing is idempotent, whether it affects all sections or just changed ones, what happens on failure, or any rate-limit/auth considerations. For a mutation-oriented tool with zero annotation coverage, this is a moderate gap.

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, purposeful sentences with zero filler. The first states the action, the second gives the timing directive. Every word earns its place.

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

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

The tool is simple (one parameter, no output schema, no nested objects), and the description explains the purpose and when to use it. However, it doesn't disclose the result of publishing (e.g., what happens to draft state, whether it returns anything, whether it's idempotent). For a publishing action this operational outcome is meaningful, and with no output schema or annotations explaining it, there's a notable completeness 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% and the single parameter (document_id) is adequately described in the schema as 'The document ID to publish.' The tool description adds no meaning beyond the schema, but with only one well-documented parameter, the schema already carries the load. 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?

States a specific verb+resource+result ('Publish an IT Glue document to make section changes visible'), which clearly communicates the tool's function. It distinguishes its role from siblings like create_document or get_document because none of those handle 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?

Provides an explicit directive: 'Always call this after creating, updating, or deleting sections.' This clearly tells the agent when to invoke the tool, referencing the sibling section operation tools (create_document_section, update_document_section, delete_document_section). Though it doesn't explicitly describe alternatives or when-not-to-use, the mandatory-use framing is strong 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 full burden of behavioral disclosure. 'Search' implies a non-destructive read, but the description doesn't state pagination behavior, result limits, whether it returns matching configs with full details, or note that it aggregates across organizations. The schema's page_size/page_number hint at pagination but the description itself adds nothing beyond the title.

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 efficient (single clause) but under-specified. It's concise in the sense of brevity, yet for a 10-parameter search tool this brevity represents under-specification rather than earned conciseness. Every word is useful, but there's insufficient content overall.

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 search tool with 10 parameters and no output schema. The description doesn't explain what the response contains, how to combine filters, whether all filters are ANDed, or the relationship with get_configuration. For a tool this configurable with zero annotation coverage and no output schema, the description is significantly under-specified.

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 every parameter has its own description in the schema. The tool description adds nothing beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting; no semantic gaps exist that the description needs to fill.

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 'Search for configurations (devices/assets) in IT Glue' with a clear verb+resource+context. It's differentiated from siblings like search_organizations and search_passwords by the specific resource type, though it doesn't explicitly distinguish from its close sibling get_configuration (which retrieves a single record vs 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention that get_configuration would retrieve a single specific configuration, or clarify that this is a list/search operation. Sibling get_configuration exists but no differentiation or exclusions are 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?

No annotations are provided, so the description carries the burden. It does disclose the metadata-only return behavior (get_document/list_document_sections needed for body), which is useful. However, it doesn't mention pagination behavior, rate limits, or filter matching semantics beyond 'partial match' (which is in the schema). The core behavioral disclosure is present but not exhaustive.

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, zero waste. The first sentence states the core purpose and scope, the second adds the critical behavioral caveat (metadata only) and points to alternatives. 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 search/list tool with 100% schema coverage and clear behavioral disclosure, this is largely complete. The only minor gap is no mention of pagination/result-count behavior (though page_size/page_number parameters are self-documenting). The metadata-only caveat plus alternative tool pointers make this genuinely helpful for agent selection.

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 org scoping context ('documents are scoped to organizations') and the metadata-only return behavior, but doesn't elaborate on parameter semantics beyond what the schema already documents. Schema covers all 6 parameters adequately.

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?

Specific verb+resource+scope ('Search for documents in IT Glue scoped to an organization'), and clearly distinguishes from siblings by stating it returns metadata only, not body — pointing to get_document as the content tool. Clear purpose with sibling differentiation.

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

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

Explicitly states it returns metadata only, not the document body, and instructs to use get_document or list_document_sections for content. This gives clear when-to-use and when-not-to guidance with named alternatives.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It communicates the required filter constraint, which is a key behavioral trait. But it doesn't disclose other behavioral aspects such as pagination behavior, whether results return full flexible asset details, or any auth requirements, leaving the agent partially uninformed.

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 concise sentence that conveys the tool's purpose and its critical constraint. No wasted words. It loses a point because it front-loads '<system>' parenthetical which is less valuable than the required-filter detail that follows.

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 6 parameters and no output schema, so the description carries responsibility for setting expectations. It adequately conveys the search purpose and requirement but doesn't describe what a successful result looks like (matching IT Glue search endpoints return flexible assets with flexible_asset_fields), pagination defaults, or use-case context. Adequate 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%, so all 6 parameters are documented in the schema with meaningful descriptions. Per the baseline rule, this earns a 3. The description itself adds little beyond the required filter hint already echoed in the schema's flexible_asset_type_id field description.

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 'Search for flexible assets in IT Glue' with a clear verb (search), resource (flexible assets), and system (IT Glue). It distinguishes from sibling tools like search_organizations and search_configurations by naming the flexible asset scope. It loses a point for not specifying what the results contain or how they differ from list_flexible_asset_types.

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

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

The description clearly notes the required filter: '(requires flexible_asset_type_id filter)', which is an explicit usage prerequisite. It gives strong context that you must provide a type ID to search. However, it doesn't explicitly contrast with list_flexible_asset_types (which returns types rather than assets within a type), limiting exclusion guidance.

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

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

No annotations are provided, so the description carries the burden. It discloses what each result includes ('address fields and phone number') and that locations are a built-in entity. However, it doesn't disclose pagination behavior, what happens on empty results, or rate limits. The description adds some behavioral context but not rich detail.

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 tight two-sentence paragraph with zero waste. It fronts the core purpose, mentions the result content briefly, and closes with a differentiation note. 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 9-parameter search tool with a well-documented schema, the description covers the key intent, result content, and tool-selection guidance. No output schema exists, but the description helpfully states what fields appear in results (address fields and phone number). It's reasonably complete for a filtered search tool, though pagination semantics are left to the schema.

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

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

Schema coverage is 100%, so the schema documents all 9 parameters. The description doesn't add parameter-level detail beyond the schema, which is acceptable given full coverage. However, it does subtly call out organization_id as 'recommended' in the schema itself, not the description. Baseline 3 is appropriate since the schema does the heavy lifting and the description doesn't add beyond it.

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

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

The description states a specific verb+resource ('Search for locations (physical addresses/sites) of an organization') and distinguishes it from a sibling: 'use this rather than search_flexible_assets to look up an organization's address or phone.' This is clear purpose with explicit sibling differentiation.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'Locations are a built-in IT Glue entity (not a flexible asset), so use this rather than search_flexible_assets.' It also implies the context (looking up organization address/phone). This is a model example of when-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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't state whether this is a read-only operation, what happens with no filters (returns all organizations?), whether results are paginated beyond what the schema implies, or what the response structure looks like. For a search tool with zero annotation coverage, more disclosure is needed.

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 efficiently conveys the core function. It's not wasteful. However, given the complexity (7 parameters, pagination, search semantics), it's slightly under-specified — a 5 would require a bit more useful context packed into that space.

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 7 optional parameters, no annotations, and no output schema, the description is notably thin. It doesn't explain default behavior (e.g., what happens when no filters are applied — does it return all organizations?), pagination semantics, whether search is case-insensitive, or how results are ordered by default. Sibling tools like search_locations and search_configurations exist, and no differentiation or cross-reference is provided. Given the tool's moderate complexity and zero annotation coverage, this is a meaningful 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 7 parameters are already documented in the schema with meaningful descriptions (name partial match, sort prefix convention, page_size max, etc.). The description adds 'optional filtering' as a general context cue but nothing beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting and the description doesn't contradict or extend it meaningfully.

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 'Search for organizations in IT Glue with optional filtering' — a clear verb (search) plus resource (organizations) plus scope (IT Glue). It distinguishes naturally from siblings like search_configurations, search_locations, and search_passwords by naming the specific resource type. It's not quite a 5 because it doesn't clarify the return format or result set nature beyond 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?

No guidance on when to use this tool versus get_organization (which retrieves a single organization) or search_configurations. There's no mention of when searching is preferred over direct retrieval, no pagination caveats, and no exclusions. The 'with optional filtering' hint implies search-all behavior but doesn't explicitly explain tradeoffs against sibling tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The metadata-only note is valuable, but the description does not disclose pagination behavior, what the return structure looks like, rate limits, or whether filters can be combined. With zero annotations, significantly more behavioral context is expected from the 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 concise sentence that front-loads the tool's purpose and its key safety caveat (metadata only). No wasted words, though it could arguably add one more sentence on usage guidance without harming conciseness.

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 8 parameters, full schema coverage, and no output schema, the description is adequately sized but lacks guidance on combining filters, expected pagination behavior, or the shape of the metadata returned. It's functional but leaves the agent to infer important behavioral details since annotations and output schema are absent.

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 every parameter has a description. The baseline is 3 per the rubric since the schema does the heavy lifting and the description adds no parameter detail beyond what's already in the schema (each parameter is self-explanatory as a filter). No additional semantic meaning is added by the description.

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+resource ('Search for password entries in IT Glue') and crucially notes it returns metadata only, not actual passwords — a key safety distinction. It differs from siblings like 'get_password' by indicating search vs retrieval, though it doesn't explicitly name the alternative tool for retrieving full 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 this is for searching/filtering password metadata but doesn't explicitly state when to use it vs get_password for retrieving actual passwords. The sibling relationship is inferable but not stated, so usage context 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?

The description goes beyond annotations by warning about HIGH-IMPACT consequences (makes the document visible to all users) and requiring confirmation before invoking. While annotations already declare destructiveHint=true, the description adds the specific visibility impact and the confirmation requirement, which is meaningful value beyond the structured metadata.

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

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

The description is efficiently written in two sentences with front-loaded warning, but it omits useful context such as error behavior or side effects (e.g., whether sections and contents are also restored). Minor redundancy exists since the title and annotation already convey reversibility.

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 tool with 100% schema coverage and a good title annotation, the description is reasonably complete. However, it doesn't cover what happens to associated sections/content, whether there's a restore delay, or potential errors. Given destructiveHint=true and openWorldHint=true, slightly more behavioral detail would improve completeness.

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

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

With 100% schema coverage, the single parameter (document_id) is fully documented in the schema as 'The document ID to unarchive'. The description adds nothing about the parameter beyond what the schema states, so baseline 3 is appropriate given the schema already handles it completely.

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 (restores/unarchives), the resource (IT Glue document), and the effect (appears in normal views, visible to all users). This distinguishes it well from the sibling archive_document and read-oriented tools like get_document or search_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 explains the high-impact reversible nature and instructs confirming with the user, but doesn't explicitly state when NOT to use it or how it differs from archive_document beyond the obvious inverse relationship. The confirmation requirement is a useful usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It confirms update is a mutation, but it doesn't state whether this saves immediately vs. drafts, whether changes are reversible, or what the response looks like (especially relevant since publish_document must be called afterward, implying this may only stage changes). The requirement to call publish_document hints at behavior but doesn't explain the state transition.

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 compact two-sentence definition with zero waste. It front-loads the core purpose and attaches the workflow caveats efficiently. Well-sized for the tool's complexity.

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 a straightforward update operation with simple parameters and no output schema. The description covers the essential workflow (fetch IDs, update, publish). However, given no annotations exist, it could benefit from disclosing the mutation's side effects and whether this requires editing permissions or draft staging.

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 three parameters adequately. The description adds minor context by mentioning that section_id comes from list_document_sections (already stated in the schema description) but doesn't add meaning beyond what the schema provides. Content is described as 'New HTML content' in the schema, which is self-explanatory.

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+resource ('Update the content of an existing IT Glue document section') that clearly states what the tool does. It distinguishes from siblings like create_document_section and delete_document_section through the word 'update' but doesn't explicitly contrast with them.

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 helpful guidance on the workflow: use list_document_sections to get section IDs first, and call publish_document after editing. It implies the proper usage sequence but doesn't explicitly state when NOT to use this tool or name alternative choices for edge cases.

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

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

No annotations are provided, so the description carries the full burden. It discloses partial-update semantics but doesn't state whether the update is destructive to unspecified fields (it implies they're preserved), whether special permissions are required, whether the primary flag has cascading effects on other locations, or what response is returned. For a mutation tool with zero annotation coverage, more behavioral disclosure is warranted.

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 zero filler. The first sentence establishes purpose and scope; the second clarifies the update model. While very brief, the description efficiently covers the core purpose without unnecessary 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?

For a partial-update tool with 13 parameters and no output schema, the description is workable but thin. It confirms the PATCH-like semantics, which is the most important behavioral trait, and schema covers all parameter names. However, no annotations and no output schema mean unclear return value expectations and no safety information. Given the tool's complexity (13 params), a bit more context about primary-location side effects or ID requirements would improve completeness.

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

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

Schema description coverage is 100%, so the schema documents all 13 parameters. The description adds the important detail that only supplied fields are changed, which adds meaning for optional parameters. However, it doesn't clarify subtle semantics like whether setting primary=true clears primary on other locations, or whether organization_id is immutable after creation. The baseline of 3 is appropriate given full schema coverage but some edge semantics are left unstudied.

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

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

The description clearly states the verb ('Update'), the resource ('existing location in IT Glue'), and the partial update semantic ('Only the fields you supply are changed'). It distinguishes from create_location (a sibling) by explicitly saying 'existing'. It doesn't name sibling alternatives, but the create/update distinction is implied by 'existing'.

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's 'Only the fields you supply are changed' conveys partial-update behavior, which is meaningful usage context. However, it provides no guidance on when to prefer this over create_location, no prerequisites (e.g., needing an existing location ID), and no note about which fields are immutable (such as organization_id). No exclusions or alternative tool references are given.

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