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

Annotations indicate non-read-only, non-destructive, and idempotent behavior. The description adds that archiving hides from normal views, is reversible via calling again with archived:false, and explicitly labels it as an update with reversible impact, going beyond annotation basics.

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

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

The description is compact, front-loaded with the core action, and uses clear operation class/impact lines. Minor redundancy and the grammatical error 'a article' prevent a perfect score, but it remains efficient 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?

For a simple two-parameter tool with strong annotations and full schema coverage, the description covers what the tool does, when to use it, its reversible nature, and its impact. No output schema is needed for this boolean toggle, and the description fully satisfies the context requirements.

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?

Both parameters are fully documented in the schema with clear descriptions for id and archived. The description reinforces the meaning of archived but does not add new information beyond the schema, so the 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 opens with 'Archive or unarchive a article', which names the exact verb and resource. It clearly explains that archiving hides without deleting and is reversible, distinguishing it from deletion and from sibling update/delete 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?

Explicitly states this is the reversible alternative to deletion and should be preferred whenever the user wants something 'removed' without permanent deletion. This provides clear when-to-use guidance and implicitly contrasts with deletion.

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

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

Annotations already indicate mutating, idempotent, and non-destructive behavior, but the description adds crucial context: archiving hides from normal views, is reversible, and archived assets remain readable via hudu_list_assets with archived:true. It also explains the API limitation (no /assets/{id} route) and the 404 behavior under a wrong company_id, which goes beyond basic annotation coverage.

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

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

The description is organized into three focused paragraphs, each earning its place. While slightly verbose, the first paragraph explains behavior and reversibility, the second addresses the critical company_id requirement, and the third gives usage guidance. No wasted words, though it could be tightened marginally.

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 boolean toggle with no output schema, the description fully covers what happens on invocation (hides or restores), the reversibility guarantee, the differentiation from delete, and the prerequisite of company_id. The behavioral and parameter coverage is sufficient for an agent to invoke this correctly without additional context.

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 clear parameter descriptions, so baseline is 3. The description adds valuable guidance on how to derive company_id from hudu_list_assets results and the consequence of using the wrong company_id (404 indistinguishable from deletion). This elevates the parameter understanding beyond the schema alone.

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 'Archive or unarchive an asset' - a specific verb and resource. It clearly distinguishes this from the sibling hudu_delete_asset by emphasizing reversibility and that it hides rather than deletes. The purpose is unambiguous and accurately reflected in the title.

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

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

The description explicitly states when to use this tool: it is the reversible alternative to hudu_delete_asset and should be preferred when a user wants a decommissioned machine 'removed' without permanent documentation loss. It also provides a concrete workflow for obtaining company_id via hudu_list_assets, which is critical for correct invocation.

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 reveals key behaviors beyond annotations: archiving hides from normal views, is reversible, and is classified as an Update. While annotations already indicate non-destructive/idempotent behavior, the description adds meaningful context about reversibility and impact, though it doesn't mention response details or side effects on related records.

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 well-structured with a clear opening, usage note, and impact summary. It is concise but slightly redundant in repeating 'reversible' across multiple sections, keeping it from being maximally tight.

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 low complexity, full schema coverage, and supporting annotations, the description fully covers what the tool does, when to use it, and its reversible impact. No output schema exists, so describing return values is not required.

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 input schema already documents both 'id' and 'archived' clearly. The description only restates the archived=false behavior for reversibility without adding new parameter-level details 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 opens with 'Archive or unarchive a company', a specific verb and resource that clearly states the tool's function. It further distinguishes itself from sibling archive tools by focusing on companies and explains that archiving hides the record without deleting.

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 advises using this tool as 'the reversible alternative to deletion' and says it should be preferred whenever the user wants something removed without permanent deletion. This provides clear when-to-use guidance relative to deletion or other operations.

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

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

Even with annotations present, the description adds substantial behavioral context: it reveals that archiving hides the record from normal views, that the action is reversible, and exactly how to reverse it (`archived: false`). It also labels the operation as Update and impact as Hide/Restore, going beyond the annotation hints.

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

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

The description is three short paragraphs, each with a distinct role: purpose, usage guidance, and operation class/impact. Every sentence earns its place, and the most critical information is front-loaded in the first sentence.

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 toggle tool with two fully described parameters and no output schema, the description covers all necessary aspects: what it does, when to prefer it, how to revert it, and its safety characteristics. An agent can confidently select and correctly invoke this tool based solely on this 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?

The input schema already provides 100% coverage with clear descriptions for both parameters. The description reinforces the `archived` boolean toggle semantics ('true archives; false restores') but does not add significant new parameter-specific meaning beyond the schema. 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 opens with 'Archive or unarchive a password,' a specific verb and resource, and immediately distinguishes the action from deletion and from editing password content. It clarifies that archiving hides from normal views and is reversible, making it distinct from sibling tools like hudu_update_password or hudu_delete (if present).

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 this is the reversible alternative to deletion and should be preferred when a user wants something 'removed' without permanent deletion. This directly tells the agent when to choose this tool over alternatives, including when not to use it (when permanent removal is intended).

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds useful behavioral context: it returns the created record with the assigned id and explains that Hudu answers 422 with the offending field on validation failure. This adds value beyond what annotations provide.

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

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

The description is concise and well-structured: it opens with the core purpose, defines the resource, and then provides operational details (return value, error handling) in a compact format. Every sentence adds value without unnecessary fluff.

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

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

The description is complete enough for a create tool: it explains what the tool creates, the return value (including the assigned id), and validation error behavior. Since there is no output schema, this is necessary and provided. It does not mention additional details like HTML requirements, but those are covered in the input schema, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, and each parameter already has detailed descriptions (e.g., HTML content, folder_id, company_id, enable_sharing). The description itself does not add new parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Create a new article in Hudu' and distinguishes it from sibling tools like hudu_update_article and hudu_get_article by specifying the create operation. It also explains what an article is and the scoping options, making the tool's function 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 clear context for when to use this tool (creating a knowledge-base article) and implies alternatives by mentioning scoping to company or global. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of the highest bar.

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

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

Annotations already indicate a non-read, non-idempotent operation, and the description adds meaningful behavior: it returns the created asset with its id, and Hudu returns 422 naming the offending field on validation failure, including nonexistent custom field labels. It also details the custom_fields shape mismatch with reads, which is valuable beyond the structured annotations.

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

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

The description is around 170 words in three focused paragraphs. It front-loads the purpose and prerequisite, then gives return/error behavior. It's slightly long but every sentence serves a distinct purpose; no filler.

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

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

The description covers purpose, required parameters, prerequisites, return value, error behavior, and a key gotcha (custom_fields shape vs read shape). For a complex create tool without an output schema, this is fully sufficient for an agent to invoke it correctly.

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

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

Input schema covers all 8 parameters with 100% description coverage, and the schema itself provides deep explanations—especially for custom_fields, including snake_case rules and read/write asymmetry. The tool description adds only a pointer to hudu_get_asset_layout for field labels, which is useful but doesn't significantly go beyond the schema. 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 opens with 'Create an asset inside a company,' a specific verb+resource statement. It defines what an asset is and contrasts with sibling tools like hudu_update_asset and hudu_archive_asset by focusing on creation. This clearly distinguishes it from other asset actions.

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 when to use it: to create an asset, with company_id required because there is no global create route. It instructs the agent to choose asset_layout_id first and explicitly points to hudu_list_asset_layouts and hudu_get_asset_layout as prerequisite lookups. It doesn't explicitly state when not to use it (e.g., for updates), so it lacks excluded 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?

Annotations already declare readOnly=false and destructive=false, but the description adds substantial context: instance-wide scope, no field edits on update, no delete endpoint, return value including the id, and 422 error behavior with the offending field named. These details go beyond what annotations provide.

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

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

The description is front-loaded with the purpose, then provides an informative definition, scope, constraints, return value, and error behavior. Each sentence earns its place; despite being longer than average, the length is justified by the tool's complexity (10 parameters and multiple behavioral constraints). 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?

With no output schema, the description appropriately explains the return value and error handling. Combined with the richly detailed input schema and annotations, the agent gets a complete picture of when and how to invoke this tool, including limitations and alternatives. Nothing important is left unexplained.

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 provides detailed descriptions for all 10 parameters, including the note about fields being the only point to supply definitions. The description does not add new parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The first sentence clearly states 'Create a new asset layout in Hudu' with a specific verb and resource. It then defines what an asset layout is, and distinguishes it from siblings by noting 'Layouts are instance-wide rather than per-company.' This makes the tool's purpose distinct from company-scoped tools like hudu_create_company.

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 when to provide field definitions: 'Field definitions can be set when a layout is created; the documented shape for changing them afterwards contradicts the shape creation accepts, so this server does not expose field edits on update.' It also gives an alternative for retirement: 'There is no delete endpoint for layouts — set active: false to retire one.' This is clear 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?

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description adds valuable behavioral context: it returns the created record including the assigned id, and it explicitly describes the 422 validation error format (naming the offending field). This goes beyond the annotations and helps the agent anticipate outcomes.

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 well-structured. It opens with the core purpose, then provides key behavioral details (return value, error handling) in a second paragraph, and ends with a brief operation class label. Every sentence adds useful information; the only minor redundancy is the 'Operation class: Create' line, but it does not detract.

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 15-parameter create tool with no output schema, the description covers the essential context: what a company is, what the tool returns, and how errors are reported. It does not explicitly mention that only 'name' is required, but that is evident from the schema. It could further suggest typical use cases (e.g., onboarding a new client), which would improve completeness, but it is otherwise adequate.

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

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

Schema description coverage is only 40% (6 of 15 parameters have descriptions), and the tool description itself provides no parameter-level guidance. The remaining 9 parameters (zip, city, state, etc.) rely on names or implicit understanding. Since coverage is low and the description does not compensate, the agent may struggle with undocumented fields.

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

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

The description clearly states the action: 'Create a new company in Hudu.' It also explains what a company is (top-level container) and that every asset, article, password, and website belongs to exactly one, which differentiates it from other company-related operations like get, update, or archive. The verb-object-resource structure 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 provides clear context for when to use the tool: creating a new top-level company. It implies this is the first step for organizing entities. However, it does not explicitly name alternatives or exclusion criteria (e.g., 'use hudu_update_company to modify an existing one'). Thus, it has clear context but no explicit when-not or 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?

Annotations indicate a non-read-only, non-idempotent create operation, and the description adds valuable behavior beyond those flags: it discloses the return value (the created record with assigned id) and the 422 validation error format with the offending field named. No contradiction with annotations is present.

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

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

The description is three sentences, front-loaded with the core purpose, then the unique scoping/nesting behavior, and finally return/error handling. Every sentence earns its place, with no redundant filler or repetition of the title.

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 there is no output schema, the description appropriately explains what the tool returns (created record with id) and error behavior (422 with field name). It also covers the global vs company context and nesting, which are critical for correct invocation. Minor missing context like auth requirements is not essential given annotations and the simplicity of a create 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?

The input schema already covers all 5 parameters with detailed descriptions, so baseline is 3. The main description reiterates parent_folder_id and company_id semantics, but this adds little beyond what the schema provides. No additional param syntax or format info is introduced that isn't already 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 clearly states 'Create a new folder in Hudu' and defines what a folder is ('groups knowledge-base articles'). It also distinguishes the tool from siblings by specifying the global vs company scope and nesting behavior via parent_folder_id, which is a concrete and unique scope.

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

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

The description explains when to use folders and how they relate to companies and global knowledge base, which helps decide whether to include company_id. It also references hudu_list_folders for copying icon values, but it does not explicitly state 'use this instead of hudu_update_folder' or provide exclusions for when not to use it.

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

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

Annotations mark this as non-read-only and non-idempotent; the description adds that the created record is returned with the Hudu-assigned id and that validation failures yield a 422 naming the offending field. This goes beyond the annotation flags, though it does not cover authentication or rate limits.

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 brief and front-loaded, with purpose, record semantics, return value, and error behavior. The 'Operation class: Create' line is redundant with the name/title and annotations, but it is minor and does not significantly detract.

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 an 8-parameter create tool with no output schema, the detailed schema descriptions plus the overview of record semantics, return value, and validation error behavior provide adequate context. It lacks explicit sibling-tool guidance, but the schema's cross-references compensate.

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 each parameter description is rich with examples and cross-references (e.g., address points to hudu_create_network for ranges; asset_id explains how to find it). The tool description itself adds no parameter-level meaning, 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 opens with 'Create a new ip address in Hudu,' a specific verb and resource. It also clarifies the semantics of an ip_address record (status, FQDN, network, asset), which distinguishes this create tool from list/get/update siblings.

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 by the verb and resource name, but the description does not explicitly state when to use this tool versus alternatives like hudu_create_network or hudu_update_ip_address. There are no exclusions or alternative references; 'Operation class: Create' adds no comparative guidance.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses that the tool returns the created record with the assigned id and that validation failures yield a 422 with the offending field named. This adds concrete behavioral context about return values and error handling.

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

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

The description is compact and front-loaded: it opens with the core action, provides a concise definition, then covers return and error behavior. Every sentence adds value, and the 'Operation class: Create' line is a clear, unnecessary-but-nice tag.

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 adequately covers the return value, error behavior, and domain context. It does not explicitly state which fields are required, but the schema covers that. Slightly more detail on prerequisites or side effects could push it to 5, but it remains complete for typical 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?

Schema description coverage is 100%, so the schema already thoroughly documents all parameters (e.g., CIDR format, company_id resolution, location_id caveats, network_type ambiguity). The description adds minimal parameter detail beyond echoing the network concept, but the schema carries the burden, warranting the baseline score.

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 specific action ('Create a new network in Hudu') and defines what a network is (a CIDR-form subnet documented in Hudu). It distinguishes from creating IP addresses by noting individual hosts are separate ip_address records, and the 'Operation class: Create' reinforces the 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 explains that networks are IP ranges and explicitly mentions that individual hosts are separate ip_address records created with hudu_create_ip_address, serving as an alternative. The schema further advises resolving company names with hudu_list_companies, giving clear when-to-use context and prerequisites.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that the created record is returned including the assigned id, and that validation failures produce a 422 response naming the offending field. This adds useful behavioral context about return value and error handling. No contradiction with annotations.

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

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

The description is front-loaded with the core action and stays reasonably concise. It includes valuable context about what a Hudu password is and gives return/error behavior. The 'Operation class: Create' line is somewhat redundant with the first sentence but not harmful.

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 13 parameters, no output schema, and basic annotations, the description is fairly complete. It explains the resource concept, return value, and error behavior. Parameter details are delegated to the schema, which is appropriate since schema coverage is 100%. It could improve by adding usage guidance versus update/list, but overall it covers the create operation well.

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?

Input schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The tool description itself adds no extra parameter-level meaning beyond what the schema already provides. It mentions optional attachment to an asset/website, but that concept is already in the passwordable_type/id descriptions.

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

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

The description uses a specific verb+resource: 'Create a new password in Hudu.' It further clarifies what a password record is and even distinguishes between API naming ('AssetPassword') and UI naming ('Passwords'). This clearly separates it from sibling tools like hudu_update_password or hudu_archive_password.

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 states what the tool does but does not explicitly say when to use it versus alternatives. There is no guidance like 'Use this when adding a new credential rather than updating an existing one' or mention of prerequisites such as resolving company_id. Some implied usage exists ('Create a new password'), but no explicit context or exclusions.

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 indicate this is a write operation (readOnlyHint=false), but the description adds valuable behavioral details: it returns the created record including the assigned id, and it describes the 422 error response with the offending field named. It also flags unit ambiguities for width, height, and max_wattage, which are important runtime caveats not visible in annotations.

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

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

The description is thorough but well-structured. It flows from purpose to domain definition, to scope distinction, to return value, and to error handling. Every sentence contributes meaningful information, and there is no filler or repetition of structured fields.

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 (8 parameters, no output schema, ambiguous units), the description covers all necessary aspects: what the resource is, how to resolve IDs, what the return value is, how validation failures are reported, and how to handle unit ambiguity. It is fully self-contained for an agent to 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?

Although the schema already covers 88% of parameters with descriptions, the tool description adds further semantic context beyond the schema, such as clarifying that rack storage is the physical container and that units for some fields are unspecified. The schema descriptions themselves are highly informative (e.g., explaining that starting_unit is not necessarily 1-based), and the overall guidance helps avoid misinterpretation.

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 'Create a new rack storage in Hudu,' clearly stating the action and resource. It also defines what a rack storage is and explicitly distinguishes it from rack storage items, which are created via separate hudu_*_rack_storage_item tools. This makes the purpose unambiguous and differentiates it from sibling tools.

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

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

The description explicitly states when not to use this tool: 'It is the container only: the equipment mounted in it is modelled separately as rack storage items, via the hudu_*_rack_storage_item tools.' It also provides actionable guidance for resolving foreign keys, such as using hudu_list_companies for company_id and hudu_list_rack_storages for location_id. This tells the agent exactly when to use this tool and how to prepare inputs.

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

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

Beyond annotations (readOnlyHint=false, etc.), the description discloses important behaviors: it returns the created record with the assigned id, Hudu returns 422 with the offending field on validation failure, and it labels 'Operation class: Create.' The parameter descriptions further disclose undocumented pitfalls like unit direction, inclusivity, and lack of conflict detection, greatly exceeding what annotations alone could convey.

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

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

The description is front-loaded with purpose and is well-organized. It is longer than average, but given the complexity and the need to warn about undocumented behaviors, every section serves a purpose. No wasted words; it could be slightly trimmed but remains effective.

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

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

This tool has 10 parameters, no output schema, and many undocumented API behaviors. The description compensates fully: it explains return values, error responses, the relationship to rack storage, and how to resolve ambiguous values via sibling tools. This is a complete and actionable description for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. However, the top-level description adds conceptual meaning by explaining how parameters relate: 'occupies the units from start_unit to end_unit on one side of the rack, and carries its own power figures.' This contextual model enhances understanding beyond individual schema entries, so a 4 is warranted.

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

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

The description opens with a specific verb and resource: 'Create a new rack storage item in Hudu.' It defines what a rack storage item is (one thing mounted in a rack) and explicitly distinguishes it from the cabinet itself, stating 'use the hudu_*_rack_storage tools for the cabinet.' This clearly positions the tool against siblings.

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 states when to use this tool versus the rack storage tools, and advises using list/get sibling tools to resolve undocumented conventions (e.g., 'Read an existing item from the same rack with hudu_list_rack_storage_items'). It does not enumerate all alternative tools but gives sufficient context for when this create tool is appropriate.

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

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

The description goes beyond annotations by disclosing that there is no update route, that the response includes the created record with the assigned id, and that validation failures return a 422 with the offending field. These are valuable behavioral details not present in the annotations.

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

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

The description is well-structured and information-dense, but the final 'Operation class: Create' sentence is redundant with the title and could be trimmed. Overall, each sentence contributes to understanding.

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

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

Given that there is no output schema, the description adequately covers the return value (created record with id) and error behavior (422). It also explains the tool's position in Hudu's relation lifecycle, making it complete for a create 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%, so the baseline is 3. The description adds extra meaning for is_inverse (warning against manual use), explains the case-sensitive internal class names for type parameters, and encourages filling the description field. This exceeds 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 the tool creates a relation in Hudu and defines what a relation is with concrete examples. It uses a specific verb and resource, and distinguishes it from siblings like hudu_list_relations.

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 tool's role and notably mentions that Hudu has no update route for relations, implying the delete-and-recreate pattern. However, it does not explicitly state when to prefer this over alternative tools or mention any prerequisites.

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

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

The description thoroughly discloses the tool's side effects: it starts recurring outbound HTTP polling plus TLS, WHOIS, and DNS lookups, and arms alerts against the owning company. It also reveals unusual behavioral traits such as the lack of a success response returning `website: null`, the risk of duplicate monitors on retry, and 422 validation errors stating the offending field—details far beyond the annotations.

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

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

The description is well-structured and front-loaded: it opens with the core purpose, then explains what a website monitor is, its side effects, usage cautions, response quirks, and operation class. Every sentence contributes critical information without redundancy, making it appropriately sized for a complex operation.

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 behavior (`website: null` on success, 422 with field on validation failure) and how to verify creation via `hudu_list_websites`. It covers side effects, parameter usage, and error handling, making it complete for an agent to select and 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?

The schema already provides 100% parameter descriptions, giving a baseline of 3. The description adds meaning by showing how the disable flags interact with each other and when to use `paused: true`, and it warns against setting checks that produce noise. However, it does not add new meaning for `notes` or `company_id` beyond the schema's already-rich descriptions.

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

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

The description explicitly states 'Create a website monitor' and immediately differentiates it from a passive documentation page, clarifying that a website in Hudu is a live monitor with scheduling and alerts. This clearly identifies the action and resource, distinct from sibling create tools like asset, article, or password.

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 offers clear context on when to use it—point it only at hosts customers own or are contracted to watch—and explains when to set `disable_ssl`, `disable_whois`, and `disable_dns` to avoid noise. It also recommends verifying with `hudu_list_websites` instead of retrying, though it does not explicitly name alternative tools for other entity types.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds only 'Operation class: Read' and scenario context, which is redundant or non-behavioral. It does not disclose error handling or multiple-match behavior, but the annotation coverage lowers the burden.

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

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

The description is three short sentences, front-loaded with the core purpose, then usage guidance and operation class. Every sentence earns its place and there is no filler.

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

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

With moderate complexity, a fully described schema, and safe-read annotations, the description covers purpose, usage context, and a key alternative. It could mention not-found or ambiguity behavior, and the response_format parameter partially addresses output, so it 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?

All four parameters have descriptions in the input schema, giving 100% coverage, so the baseline is 3. The description adds no parameter-specific syntax or further semantics beyond the schema, but no additional compensation is needed given the complete 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 resolves a company from a connected integration to its Hudu company record, using a specific verb and resource. It also distinguishes itself from hudu_list_companies by explicitly naming the alternative for name-based lookup.

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 says to use this tool when arriving from another system with that system's customer id, and directs name-based lookups to hudu_list_companies with search. This gives clear when-to-use guidance and a direct alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds valuable context: no IDs needed, only a valid key, returns only two fields, and explains the 404-vs-nonexistent ambiguity. This enriches the agent's understanding beyond the structured hints.

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 well-organized and front-loaded with the core purpose. All sentences provide value except the final 'Operation class: Read' which redundantly echoes annotations, but it is a minor inefficiency.

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 diagnostic tool with no output schema, the description fully covers what it returns, when to use it, why it's useful, and its minimal requirements. It is complete for an agent to select and invoke this 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 coverage is 100% with a well-described optional parameter (response_format). The tool description itself does not mention this parameter, but the schema fully documents it, so the description adds no extra meaning. 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 function: 'Report the version and build date of the Hudu instance'. It specifies the exact output (version and date) and nothing else, which distinguishes it from all sibling CRUD 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?

Explicitly instructs to 'Call this first whenever something behaves unexpectedly' and explains why in detail (API version differences, 404 ambiguity, confirming base URL/API key). This gives clear when-to-use guidance, even without naming 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context: articles are HTML knowledge-base documents, may be scoped to a company or be instance-global, and that 404s are indistinguishable. This is more than the annotations alone provide, though it doesn't cover response shape or error cases in depth.

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

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

Three sentences plus a one-line operation class. Every sentence earns its place: the core action, domain context, and a critical usage caveat. No redundant elaboration.

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 2-parameter get with no output schema, the description covers the resource nature, global/company scoping, and the 404 ambiguity. It doesn't describe the exact return payload, but the response_format parameter and article description provide sufficient understanding. Slightly more detail about response content would push it to 5.

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% — both id and response_format are already documented in the schema. The description mostly reiterates 'numeric id' and provides domain context, but adds no new parameter-level meaning beyond the schema. 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 opens with 'Fetch one article by its numeric id' — a specific verb, resource, and lookup key. It distinguishes this get tool from sibling hudu_list_articles by explaining that ids are required and not guessable, and explicitly points to list for name-based lookup.

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 use hudu_list_articles when only a name is known, and cautions that 404 responses are ambiguous (missing vs. unrouted). This gives clear when-to-use and when-not-to-use guidance beyond generic phrasing.

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?

While annotations already indicate read-only and idempotent behavior, the description adds non-obvious API details: assets are readable globally but written per company, there is no /assets/{id} route, and the fields array structure of {id, label, value, position}. This contextual information goes well beyond the structured fields.

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

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

The description is well-structured and front-loaded with the core purpose, followed by workflow guidance and return structure. Each sentence contributes useful information, though the final 'Operation class: Read' is redundant with the readOnlyHint annotation, slightly preventing a perfect score.

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-asset fetch without an output schema, the description covers the required identifiers, the layout-driven fields, and a warning about update behavior. It does not enumerate all top-level return fields, but the 'every value' phrase plus the fields array explanation gives sufficient context for an agent to understand 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 coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description adds meaningful context, especially for company_id: why it is mandatory, that it is not guessable, and how to source it from other tool responses. This elevates it beyond the schema's baseline.

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

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

The description opens with 'Fetch one asset with every value stored on it', a specific verb-resource pair that clearly distinguishes it from list-focused siblings like hudu_list_assets. It also defines what an asset is and explains the layout-driven fields, making the tool's purpose unambiguous.

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

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

The description explicitly states the need for both company_id and id, explains the lack of a /assets/{id} route, and provides step-by-step instructions for obtaining company_id via hudu_list_assets. It also advises reading the asset here before any update because a PUT replaces values, establishing clear 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: layouts are instance-wide, field edits are not exposed on update due to an API contradiction, and there is no delete endpoint. These are non-obvious traits that help an agent predict tool behavior without running it.

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 well-organized: the main action is front-loaded, followed by a definition, scope, and key caveats, then an explicit alternative tool. Every sentence contributes unique information, and the length is appropriate for the tool's complexity. The trailing 'Operation class: Read' is slightly redundant with annotations but does not hurt.

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

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

For a read tool with no output schema, the description provides all essential context: what an asset layout is, its instance-wide scope, mutation limitations (no field edits, no delete), and a lookup strategy (list first). This makes the tool fully navigable by an agent without needing additional external knowledge.

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 complete documentation for both parameters (id description and response_format enum/description), with 100% coverage. The description adds minimal extra parameter meaning—only clarifying that ids are not guessable, which is more of a usage hint than a semantic of the id parameter itself.

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

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

The description opens with a specific verb and resource: 'Fetch one asset layout by its numeric id.' It clearly distinguishes from the sibling hudu_list_asset_layouts by emphasizing the numeric id retrieval, and the surrounding context (layout definition, instance-wide scope) further clarifies what this tool uniquely returns.

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?

Explicit guidance is given: 'Use hudu_list_asset_layouts first if you only know a name' is a direct alternative recommendation, backed by the caveat that 'ids are not guessable' and that 404 responses are ambiguous. It also notes the lack of a delete endpoint and suggests the active:false retirement path, which helps agents choose the right action.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the 404 behavior for missing records vs unrouted paths, and explains that a company is a top-level container. No contradiction, but it does not go deeper into response shapes or error handling.

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 first two sentences are concise and information-dense. The third sentence, 'Operation class: Read.', is redundant given readOnlyHint=true in annotations, so a small deduction. Overall it is appropriately sized 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?

For a simple read-by-id tool with full schema coverage and strong annotations, the description provides sufficient context: how to get the id, what a company is, and 404 behavior. It does not describe the return value, but the tool's purpose makes that inference straightforward. It feels complete for selection and 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?

Schema descriptions cover 100% of parameters, including the id type and response_format enum. The description adds no new parameter-level detail beyond the schema; the note about numeric id and non-guessability is more of a usage guideline than parameter semantics.

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 'Fetch one company by its numeric id', which is a specific verb, resource, and identifier. It clearly distinguishes this from hudu_list_companies (list vs fetch by id) and other getter tools by emphasizing the unique id-based access.

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 use hudu_list_companies first when only a name is known, and explains why: ids are not guessable and 404s are ambiguous. This gives clear decision guidance relative to the alternative tool.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses that IDs are not guessable, that 404 is ambiguous, and that folders nest via parent_folder_id or belong to a company via company_id. This enriches the agent's understanding of the API's behavior.

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

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

The description is concise and well-structured: a clear single-sentence purpose, a compact explanation of folder semantics, and an explicit usage note. Every sentence 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?

For a simple read operation with strong annotations and schema coverage, the description covers purpose, error semantics, related resource context, and when to use an alternative. It is 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?

The input schema already provides complete descriptions for both parameters (id and response_format), so the description's value here is marginal. It reinforces that id is numeric and mentions that IDs are not guessable, but this is more usage guidance than parameter-specific detail.

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

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

The description opens with a specific verb+resource+scope: 'Fetch one folder by its numeric id.' It further clarifies that folders group knowledge-base articles and can be scoped by company_id, distinguishing this from sibling get/list tools like hudu_get_article or hudu_list_folders.

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

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

Explicit usage guidance is provided: 'Use hudu_list_folders first if you only know a name — ids are not guessable, and Hudu answers 404 identically for a missing record and an unrouted path.' This tells the agent when to use an alternative and explains important error behavior.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, so the description's 'Operation class: Read' adds little. However, it adds value by disclosing that ids are not guessable and that Hudu returns 404 identically for missing records and unrouted paths, which is useful error-handling context.

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 short, front-loaded with the primary action, and every sentence serves a purpose. The final 'Operation class: Read' is slightly redundant with annotations but not wasteful.

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

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

For a simple get-by-id tool with no output schema, the description is complete: it defines what an ip_address record contains, explains how to find the ID, and warns about the 404 behavior. No critical operational detail is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic context for the id parameter ('ids are not guessable') and clarifies the record concept, going beyond the schema's property descriptions.

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

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

The description opens with a specific verb and resource: 'Fetch one ip address by its numeric id.' It clearly identifies the tool's scope (single record by ID) and distinguishes it from sibling tools like hudu_list_ip_addresses, which lists records.

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

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

The description provides explicit guidance: 'Use hudu_list_ip_addresses first if you only know a name — ids are not guessable.' It also explains the 404 ambiguity, giving a concrete reason to prefer the list tool as a prerequisite.

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

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

Annotations already declare readOnly/idempotent/non-destructive traits. The description adds valuable context about network ownership and the identical 404 behavior for missing records and unrouted paths, which is not inferable from annotations alone.

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

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

The description is three sentences with no fluff, front-loading the core action, then providing needed domain context and usage guidance. Every sentence serves a 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 simple read-by-id tool with rich annotations and fully described schema, the description provides complete context: what it does, what a network is, when to use it, and notable edge-case behavior. No gaps remain.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description does not add parameter-specific details beyond what the schema provides, meeting the baseline but not exceeding 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 clearly states it fetches one network by numeric ID, distinguishing it from list, create, and update sibling tools. The verb 'Fetch' and resource 'network' are specific, and the context about CIDR form adds 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?

Explicit guidance is given to use hudu_list_networks first when only a name is known, and the non-guessable IDs plus identical 404 responses justify the need for that preliminary step. This directly addresses when to use this tool vs. 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds valuable nuance beyond annotations: Hudu returns 404 identically for missing records and unrouted paths, and IDs are not guessable. This helps the agent reason about error handling. The 'Operation class: Read' line is redundant but harmless.

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 well-structured: it states the action first, provides resource context, then gives usage guidance and a behavioral warning. Every sentence contributes value 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?

For a simple read tool with rich schema and annotations, the description covers the essential context: what the resource is, how to obtain the id, and how errors behave. The only gap is not describing the return value structure, but the title and purpose make it clear that it fetches a password record. Given the tool's simplicity, this is sufficiently complete.

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

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

The schema has 100% coverage with clear descriptions for both parameters (id as numeric Hudu id, response_format with enum and default). The description does not add substantial meaning beyond the schema, though it reinforces 'numeric id.' This is acceptable given schema coverage, so a 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 opens with a specific verb and resource: 'Fetch one password by its numeric id.' It clearly distinguishes from siblings like hudu_list_passwords (list all) and hudu_update_password (update) by focusing on a single fetch operation. The added context of what a password record is in Hudu further grounds 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 explicitly instructs: 'Use hudu_list_passwords first if you only know a name — ids are not guessable.' This gives a clear when-to-use versus alternative guidance. It also warns about the 404 behavior, helping the agent interpret failures correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: that folders can carry access restrictions affecting visibility, and that Hudu returns 404 identically for missing records and unrouted paths — these go beyond the annotation hints.

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

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

The description is compact and well-structured: it opens with the core purpose, adds domain context, then gives usage guidance. Every sentence contributes, with no redundancy or filler.

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

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

This is a simple fetch tool with strong annotations and complete parameter schema. The description covers purpose, usage, and key behavioral quirks (404 handling, access restrictions). It does not explicitly describe the return object, but the action 'Fetch one password folder' plus the response_format parameter make this sufficiently clear.

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 both parameters. The description supplements this by explaining that ids are not guessable and recommending a lookup workflow, adding meaningful semantics to the id parameter beyond its schema type and 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 action ('Fetch one password folder by its numeric id') with a clear resource and identifier, distinguishing it from siblings like hudu_get_password (which fetches a credential, not a folder) and hudu_list_password_folders (which lists, not fetches).

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 instructs to use hudu_list_password_folders first when only a name is known, explains that ids are not guessable, and warns about the 404 behavior — providing clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable context beyond those: the 404 identical response for missing vs unrouted paths and the fact that ids are not guessable. It also explains that 'procedure' is called 'Process' in the UI. This adds behavior/terminology context that annotations do not capture.

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

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

The description is front-loaded with the core action, followed by a brief conceptual definition and a single usage-guidance sentence. Every sentence adds value; no filler. It is compact despite covering terminology and error behavior.

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 fetch-by-id tool, the description covers the key elements: what it returns conceptually (ordered checklist with completion count), how to obtain the id (via list), and the ambiguous 404 behavior. It omits a detailed return schema, but no output schema is provided and the tool is read-only, so this is acceptable. The description is well-suited to 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 description coverage is 100%, with 'id' described as 'Numeric Hudu id of the procedure' and 'response_format' fully documented with enum and default. The description does not add any parameter-specific semantics beyond restating 'numeric id' and the conceptual definition. Therefore the 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 opens with 'Fetch one procedure by its numeric id,' a specific verb+resource combination. It distinguishes itself from sibling tools by contrasting with hudu_list_procedures (for name-based lookup) and clarifies the Hudu/Process terminology. This clearly identifies the tool's function among many related list/get/update/archive 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?

Explicitly instructs to 'Use hudu_list_procedures first if you only know a name,' and explains why (ids are not guessable, 404 ambiguity). This gives a clear when-to-use and when-to-use-alternative directive. Also labels 'Operation class: Read' to set expectations.

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

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

Beyond the readOnly/idempotent annotations, the description reveals that ids are not guessable and that Hudu answers 404 identically for a missing record and an unrouted path. It also clarifies the scope boundary with rack storage items, adding behavioral context not present in annotations.

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

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

The description is front-loaded with the action sentence, followed by a concise definition, usage guidance, and an operation class note. Every sentence earns its place; no repetition or filler.

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

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

For a simple get-by-id tool, the description is complete: it defines the resource, explains how to obtain the id, warns about the 404 behavior, and distinguishes from item tools. With comprehensive schema and annotations, no critical information is missing.

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

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

The schema covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaning to the 'id' parameter by noting it is numeric and must be obtained via list, which is valuable beyond the schema's 'Numeric Hudu id of the rack storage.'

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 'Fetch one rack storage by its numeric id,' a specific verb+resource statement. It further distinguishes the tool from the hudu_*_rack_storage_item tools by clarifying that rack storage is the container only, which disambiguates it from related tools.

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

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

It explicitly advises 'Use hudu_list_rack_storages first if you only know a name,' and explains the 404 ambiguity, giving the agent clear when-to-use and when-not-to-use guidance. This is a strong alternative-aware instruction.

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?

ReadOnlyHint, idempotentHint, and destructiveHint are already in annotations. The description adds useful behavioral context about non-guessable ids and the ambiguous 404, which is beyond the annotations. 'Operation class: Read' merely restates annotations, offering no extra 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 concise and front-loaded, with each sentence serving a purpose. The definitional second sentence and the list-first guidance both aid understanding; only the 'Operation class: Read.' line is slightly redundant with annotations.

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

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

For a simple get-by-id tool with 2 parameters and no output schema, the description covers the core operation, defines the resource, and includes error ambiguity. It doesn't describe the return value, but that's implicitly the requested item and the schema's response_format param covers output shape.

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

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

Schema coverage is 100%, so parameters are fully described in the schema. The description echoes that id is numeric but doesn't add new parameter semantics beyond the schema's own descriptions.

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

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

The description opens with 'Fetch one rack storage item by its numeric id,' a specific verb-resource pair. It further distinguishes rack storage items from the rack storage cabinet, referencing hudu_*_rack_storage tools, which differentiates this from sibling tools like hudu_get_rack_storage.

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 instructs to use hudu_list_rack_storage_items first when only a name is known, explains ids are not guessable, and notes the identical 404 response, setting clear expectations for when this tool should and shouldn't be used.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: what an upload is, the fields it carries, and the fact that ids are not guessable. The 'Operation class: Read' is somewhat redundant with annotations but not contradictory. This exceeds baseline transparency.

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

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

The description is three focused sentences, with the purpose front-loaded. Every sentence earns its place: the first states the function, the second defines what an upload is and its key attributes, and the third gives usage guidance. The 'Operation class: Read' line is slightly redundant with annotations but minor. No fluff or irrelevant 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 simple get-by-id tool with no output schema, the description is remarkably complete. It explains the return fields (url, name, mime, size, uploadable_type/uploadable_id), the types of records it can be attached to, and the recommended flow (list first if only name is known). It also clarifies the 404 behavior. The absence of an output schema is mitigated by the field list included in the 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% for both parameters, so the baseline is 3. The description adds meaning by explaining why 'id' is required and how to obtain it (via list), and it introduces the concept that ids are not guessable. This context enriches the schema's simple 'Numeric Hudu id of the upload' 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 starts with a specific verb and resource: 'Fetch one upload by its numeric id.' It clearly distinguishes itself from sibling tool hudu_list_uploads by advising to use the list tool when only a name is known. This makes the tool's unique purpose unmistakable.

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

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

It explicitly states when to use this tool versus an alternative: 'Use hudu_list_uploads first if you only know a name — ids are not guessable.' It also provides a behavioral caveat about 404 responses, guiding the user on error interpretation. This is clear, actionable usage guidance.

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

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

Beyond annotations already marking readOnly/idempotent/destructive hints, the description adds crucial behavioral context: id non-guessability and identical 404 responses for missing records vs unrouted paths. This enriches safety expectations without contradicting annotations.

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

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

Three short paragraphs with front-loaded purpose, no filler. The 'Operation class: Read' line is a concise concluding marker. Every sentence earns its place.

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

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

For a simple read-by-id tool with no output schema, the description covers the entity definition, prerequisite discoverability, response ambiguity caveat, and safety class. No significant gaps remain.

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

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

Schema coverage is 100% for both parameters. The description further explains that ids are not guessable and points to list_users for name-based lookup, adding value to the id parameter beyond the schema's simple 'Numeric Hudu id'.

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 'Fetch one user by its numeric id' – a specific verb, resource, and method. It also clarifies what a user is (team member or portal member) and naturally distinguishes itself from hudu_list_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?

It explicitly instructs to 'Use hudu_list_users first if you only know a name' and explains why (ids are not guessable, 404 ambiguity). This is a clear when-to-use vs alternative 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?

The description adds behavioral context beyond annotations: it explains that Hudu polls the host on a schedule and records uptime, TLS, WHOIS, and DNS, and that a 404 is ambiguous between missing record and unrouted path. Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the description supplements rather than repeats the safety profile. No contradiction exists.

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

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

The description is front-loaded with the core action in the first sentence, followed by useful domain context and usage guidance. The final 'Operation class: Read' is slightly redundant given the annotation, but the overall structure is efficient and earns its place. Six sentences for a simple tool is appropriate.

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

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

For a read tool with 2 well-documented parameters and no output schema, the description provides sufficient context: what a website is, what data it contains, and the 404 ambiguity. The user can infer the return shape from the entity description (uptime, TLS, WHOIS, DNS). The tool is simple enough that this is a complete 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 coverage is 100%, with descriptions for both 'id' and 'response_format' including default and enum meaning. The description itself adds no parameter-level detail beyond 'numeric id', so it correctly relies on the schema. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description opens with 'Fetch one website by its numeric id', a specific verb+resource+method that clearly distinguishes it from list/create/update siblings. It further clarifies that a website is a live monitor rather than a documentation page, removing ambiguity with article/procedure tools. Operation class: Read reinforces the read-only nature.

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?

Explicit guidance: 'Use hudu_list_websites first if you only know a name — ids are not guessable, and Hudu answers 404 identically for a missing record and an unrouted path.' This tells the agent exactly when to prefer the list tool and warns against id guessing. No other when-not-to-use is needed for a simple get 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?

The description goes well beyond annotations by explaining that the procedure's task list is copied into a new process with its own id/slug/URL, the original procedure is unchanged and reusable, and the resulting process appears as outstanding work in the company's process list. It also describes HTTP status behavior (200 vs 201, 404 meaning both missing procedure and unrouted path) and that no request body is accepted, which are valuable execution details.

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 structured into clear paragraphs: one for core behavior, one for parameter guidance, and one for endpoint details. Every sentence serves a purpose, no filler. While longer than minimal, the density of useful information justifies its length, and the most important action is 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?

For a create operation with no output schema, the description covers the essential context: what is created (live process with its own record), how it affects the company, how to attach assets, the status code nuances, and the operation's impact. This is complete for an agent to select and invoke the tool correctly without needing additional documentation.

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

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

The schema already covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaningful usage examples for asset_id ('onboarding checklist ends up on the employee record') and name ('Onboarding — J. Okafor'), which helps agents decide when to provide these optional parameters. It doesn't add much for the required id beyond redirecting to hudu_list_procedures, but overall it enhances schema semantics.

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

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

The description opens with a specific verb and resource: 'Start a new process from an existing procedure.' It clearly explains the copy behavior and that the procedure remains unchanged, which distinguishes it from other Hudu tools like listing or getting procedures. The title also aligns, and the scope is 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 explicit usage context: when to attach an asset ('when the work concerns one specific device or person'), when to set a name ('when several runs of the same procedure would otherwise be indistinguishable'), and how to find the procedure id (via hudu_list_procedures). It does not explicitly contrast with alternative tools for creating processes, but no sibling serves this exact role, so the guidance 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?

Beyond the annotations (readOnlyHint, idempotent, not destructive), the description discloses that entries are ordered by Hudu not the server, there is no total count returned, and page_was_full is the only honest pagination signal. It also explains the read-only nature explicitly, which is consistent with annotations.

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

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

The description is long but well-organized with bullet points and clear sections. It front-loads the purpose and then systematically covers parameter behaviors. Some redundancy exists (no total count is mentioned twice), but the complexity of the 10-parameter tool justifies the length.

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 10 parameters and no output schema, the description is remarkably complete. It covers return shape (items plus pagination facts), filter combinations, ordering, pagination caveats, and the distinction from the destructive purge tool. No operational aspect is left unaddressed.

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?

Even though the input schema already covers all parameters with descriptions, the tool description adds substantial semantic context: resource_type and resource_id must be used together, start_date should include an explicit UTC offset, action_message has no enumerated values, and fields can be used to keep lists small. This goes far beyond the schema details.

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

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

The description opens with 'List activity logs in Hudu' and then defines the tool as 'the tool for who changed this, and when', giving a clear verb+resource+scope. It describes the audit trail contents (actor, resource, action) which distinguishes it from other list tools, and explicitly contrasts with the destructive purge 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?

It provides explicit 'when to use' guidance ('who changed this, and when') and detailed filter combination rules, including what not to do (e.g., sending resource_type without resource_id does nothing). It also points to an alternative destructive tool (hudu_purge_activity_logs) for purging, helping the agent avoid misuse.

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

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

Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: every record contains full HTML content which is large, the API returns no total count, page_was_full is the only signal for more records, there is no documented archived filter, and the fields parameter ignores unknown names. These details are not available in the schema or annotations and are essential for correct use.

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 long but every sentence earns its place. It opens with a clear definition, then systematically covers filters, the critical fields caveat, and pagination honesty. It is front-loaded with the most important information and avoids redundancy or vague phrasing.

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 list tool with 11 parameters and no output schema, the description is remarkably complete. It explains the returned shape ('object with items plus pagination facts'), the lack of a total count, the absence of an archived filter, and even notes the response_format option. The description fully prepares an agent to use the tool correctly in every scenario.

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?

While the schema already covers all 11 parameters, the description adds significant meaning beyond the schema: company_id scoping and the null-selection workaround, the audit use case for enable_sharing, the published/draft distinction with the note that draft is not writable, and the performance impact of full content with guidance to pass fields. This transforms mere parameter names into actionable knowledge.

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

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

The description clearly states 'List articles in Hudu' and explains what an article is (knowledge-base document with HTML content, optional folder/company scoping). It distinguishes from sibling hudu_get_article by noting that after filtering with 'fields' you should 'fetch the body with hudu_get_article'. It also highlights specific use cases like auditing public exposure via enable_sharing, making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: use enable_sharing for 'what of ours is exposed publicly?', use draft for unpublished work, and use the 'fields' parameter when looking for an article rather than reading one, then fetch the body with hudu_get_article. It also explains what not to do (there is no archived filter, so archived articles cannot be selected) and how to handle global-only articles by omitting company_id and selecting on null.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: layouts are instance-wide, field edit semantics are intentionally not exposed, pagination is server-sized, and the API returns no total count so page_was_full is the only reliable pagination signal. These go far beyond annotation defaults.

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 long but every sentence carries crucial information. It front-loads the core purpose, then organizes caveats into logical paragraphs covering layout properties, update limitations, pagination behavior, and output shape. No fluff, 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?

With no output schema, the description takes on the full burden of explaining return values ('items plus pagination facts'), pagination semantics ('page_was_full', 'pagination_note'), and API quirks (no total count). It also explains how this tool feeds into asset creation/update, making it self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the page parameter's server-controlled page size and the deeper meaning of the fields array in relation to hudu_create_asset/hudu_update_asset, but most parameter semantics are already well-documented 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 opens with the specific verb+resource ('List asset layouts in Hudu') and elaborates on what an asset layout is, making the tool's purpose unmistakable. It clearly differentiates from sibling tools like hudu_get_asset_layout by focusing on the collection-level list 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?

Provides explicit guidance on when to use this tool: 'Read this before writing any asset' to determine custom_fields keys for create/update. Also states exclusions—no delete endpoint (use active:false) and no field edits on update—and explains pagination caveats so the agent knows what to expect.

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 well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing that the API returns no total count, so page_was_full is the only honest signal for more records, and 'pagination_note' should be read. It also reveals the shape of custom fields under 'fields' and explains response_format behavior, adding genuine behavioral context.

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 longer than average but every paragraph earns its place: the first defines assets, the second covers scope and relationship to write endpoints, the third explains custom fields and filtering strategy, and the last covers return shape and pagination quirks. It is well-structured and front-loaded, though slightly verbose in places.

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 13 parameters, no output schema, and no documented total count, this description is exceptionally complete. It explains the return shape ('object with items plus pagination facts'), how to handle pagination honestly, how to use fields and search, and the relationship to write operations. Nothing essential is left unexplained.

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

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

Although schema coverage is 100%, the description enriches nearly every parameter with practical guidance: fields 'use it to keep large lists small', page_size explains the client clamps at 100 and rejects larger values, updated_at explains the ISO-8601 range format with examples, and id explains its role in recovering company_id. This adds meaning beyond the schema definitions.

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 assets in Hudu'), defines what an asset is, and distinguishes this tool from siblings by stating it is 'the only route that reads assets across every company.' This clearly differentiates it from hudu_list_company_assets and other asset-related tools.

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

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

The description explicitly states when to use this tool versus others, including that it is the only cross-company read route, that write operations live under /companies/{company_id}/assets, and that 'search' is the best first filter. It also warns to keep company_id because it cannot be recovered from asset id, and mentions hudu_get_asset as an alternative for getting a single asset.

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 signal read-only, idempotent, and open-world behavior, but the description adds vital details: the Hudu API returns no total count, 'page_was_full' is the only honest pagination signal, and scoped keys cause 404s. These go beyond the annotations and materially shape how the agent should interpret results.

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 few focused paragraphs with front-loaded purpose. The final 'Operation class: Read' is redundant given readOnlyHint=true, but the rest of the content is efficiently ordered and each sentence provides distinct information about the tool's quirks and usage.

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

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

Given the tool has 14 parameters, no output schema, and significant pagination quirks, the description covers the essential context: return shape, pagination honesty, scoping constraints, and key filter guidance. It does not need to repeat schema details, and the missing pieces (e.g., exact field list) are not critical for correct invocation.

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

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

Schema description coverage is 71%, and the description adds semantic value by distinguishing 'search' (broad) from 'name' (exact field) and explaining the clamped page_size behavior. This is extra guidance beyond the schema's per-parameter descriptions, though the schema already carries most of the parameter intent.

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 'List companies in Hudu', a specific verb+resource statement, and clarifies that a company is the top-level container in Hudu. This makes the tool's purpose unambiguous and distinct from sibling get/list tools by naming the exact resource and 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 provides clear in-tool guidance: 'prefer search over name' for finding by name, and warns that a company-scoped API key only exposes that company (everything else 404). It does not explicitly name alternatives like hudu_get_company, but offers enough contextual usage direction to guide the agent.

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

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

Annotations already declare readOnly/idempotent/destructive hints, and the description adds valuable behavioral context beyond those: pagination lacks a total count, page_was_full is the only reliable signal for more records, and company_id scoping causes 404 for mismatched owners. This extra disclosure (e.g., 404 ambiguity, no total count) meaningfully enriches the agent's understanding.

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 organized into three clear paragraphs: definition, scope/alternative, and return/pagination. Each paragraph earns its place, but it is slightly longer than the minimum needed. The 'Operation class: Read' footer is redundant given annotations, but not harmful.

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 appropriately explains the return shape ('items' plus pagination facts, page_was_full signal) and the influence of asset layout on custom fields. It covers the key nuances needed to use the tool correctly, including limitations and alternatives, making it complete for a list operation with this 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 detailed parameter descriptions, so baseline is 3. The description adds value by clarifying that only paging and archived are accepted—meaning no filtering—and by directing users to hudu_list_assets for filter support. This helps an agent decide whether this tool's parameter set meets the need, though it doesn't detail syntax 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 opens with a specific verb+resource: 'List the assets belonging to one company.' It also defines what an asset is, which disambiguates from other resources. It distinguishes itself from the sibling hudu_list_assets by noting this route accepts only paging and archived, while hudu_list_assets supports full filtering.

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?

Explicit when-to-use guidance is provided: 'To filter by name, serial, layout or free text within a company, call hudu_list_assets with company_id set instead — it reaches the same records and supports the full filter set.' It also states what the route accepts ('paging and the archived flag and nothing else'), making the scope 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?

Beyond annotations, the description discloses that expirations are read-only, that the API returns no total count so page_was_full is the only honest pagination signal, and that entries are not filtered by past dates. It also explains the entry structure uses expirationable_type/id rather than embedding the full record, which is valuable context not present in annotations.

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

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

The description is longer than average but well-structured and front-loaded with a clear definition of expiration. Each paragraph covers a distinct aspect: purpose, filtering, entry structure, pagination behavior, and read-only nature. While verbose, every sentence adds meaningful information and the structure aids scanning.

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?

Without an output schema, the description fully explains the return shape (items plus pagination facts), the entry references via expirationable_type/id, and the date field. It also covers pagination limitations, the lack of date filtering, and how to modify expirations, making the tool's behavior complete for an agent to invoke 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?

The input schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds minimal extra parameter-specific meaning beyond schema, only mentioning company_id as a typical first filter and the need to read the date field. It does not expand on page, fields, or expiration_type beyond what the schema already states.

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

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

The description clearly defines the tool as listing expirations in Hudu, with a specific explanation of what an expiration is. It positions this as the single call to answer 'what is about to expire' and contrasts it with walking websites, assets, and articles separately, distinguishing it from sibling tools.

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

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

The description explicitly states when to use this tool: to get expiry dates across modules without walking each separately. It advises filtering by company_id and warns that there is no date-range filtering, telling users to compare the date field themselves. It also directs users to fetch underlying records with specific sibling tools (hudu_get_website, hudu_get_asset, hudu_get_article).

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

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

Beyond the annotations, the description discloses that the response is flat (not a tree), that hierarchy must be reconstructed via parent_folder_id, and that the API returns no total count. It also transparently explains the ambiguous in_company parameter and advises verifying with company_id, adding significant behavioral context not available from annotations alone.

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

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

The description is compact yet information-dense. Every sentence earns its place: purpose, differentiation, response structure, parameter caveat, pagination note, and operation class. It is well-organized and 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?

With no output schema, the description takes responsibility for explaining the return shape, which it does thoroughly: items, pagination facts, page_was_full as the only honest signal, and pagination_note. It also covers hierarchy reconstruction and company scoping, making it complete for a list tool of this 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 description coverage is 100%, so baseline is 3. The description adds meaningful nuance: it explains the undocumented behavior of in_company and suggests omitting it rather than sending false, and it clarifies the practical effect of page_size clamping. This goes beyond simple schema documentation, earning a 4.

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 clear verb+resource: 'List folders in Hudu.' It then explicitly differentiates from sibling tools by stating that password folders are a separate resource with their own tools and 'do not use these ids there.' This uniquely positions the tool against the many sibling list tools.

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

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

The description clearly states when to use the tool (listing article folders) and explicitly warns against using folder IDs for password folders, pointing to the separate password_folders resource. It also provides practical guidance on in_company behavior and pagination, telling the agent to read pagination_note before concluding a list is complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds vital non-obvious behaviors: no paging (no page/page_size), `truncated` flag for response budget cuts, no total count in the API, and the need to check `page_was_full` and `pagination_note`. It also warns that unfiltered calls can return tens of thousands of records, which is beyond annotation scope.

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 long but the length is justified by the endpoint's risky default behavior. It is organized into clear paragraphs covering record definition, paging/truncation warnings, filter guidance, and return shape. The final 'Operation class: Read' is redundant with annotations and could be trimmed, but the rest is purposeful 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?

For a 10-parameter list endpoint with no output schema, the description covers all essential context: response shape (items + pagination facts), absence of total count, meaning of `page_was_full`, and `truncated` flag. It also warns about large deployments, points to related tools, and gives filter strategies. This is complete enough for safe and effective 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?

With 100% schema coverage, the baseline is 3, but the description adds significant practical value: it clarifies that `address` matches exact stored text and cannot find subnet hosts, recommends `network_id` as the narrowest/safest filter, provides a `fields` example to keep responses small, and links `asset_id` to hudu_list_assets. This transforms raw parameter definitions into actionable strategy.

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

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

The description clearly states 'List ip addresses in Hudu' and explains what an ip_address record documents. It distinguishes itself from sibling tools like hudu_get_ip_address (single record) and hudu_list_assets (assets) by focusing on the address-centric list operation and explicitly mentioning the lack of paging.

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

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

The description gives explicit when-to-use guidance: 'Always send a filter — network_id for one subnet, company_id for one customer, address or fqdn when you are chasing a single host.' It also points to hudu_list_assets for going from an address to a machine and cautions against using `address` to find subnet hosts, recommending `network_id` instead.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses pagination behavior: no total count, page_was_full as the only honest signal, and the instruction to read pagination_note. It also reveals that the write side uses company_name while the read side uses company_id, adding valuable behavioral nuance.

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 well-structured with clear paragraphs: definition, write/read naming asymmetry, single-fetch limitation, return shape/pagination, and operation class. Every sentence adds value, and the most important information (what it lists) is 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?

With 6 parameters, no output schema, and a complex domain (magic dash items), the description covers all necessary context: return shape (items + pagination facts), pagination caveats, read-only nature, and filtering strategies. It fully compensates for the lack of an output schema.

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

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

Despite 100% schema coverage, the description adds critical parameter meaning: company_id is 'a read-side filter only', titles are not unique, and fields is useful for keeping lists small. It also clarifies page_size clamping behavior, going beyond the schema's basic descriptions.

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

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

The description states 'List magic dash items in Hudu' and explains what a magic dash item is with a concrete example. It clearly distinguishes this read tool from the sibling write tool hudu_upsert_magic_dash_item by noting the asymmetry between read (by company_id) and write (by company_name).

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

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

The description explicitly says there is no single-fetch endpoint, so this list is the only way to read a tile, and advises filtering by title and company_id. It also warns that write endpoints identify companies by name, providing practical when-to-use context not available in schemas.

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

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

Beyond the readOnlyHint annotation, the description reveals important API quirks: no total count endpoint, reliance on page_was_full for pagination, and no endpoint to list integrations. It also describes what unmatched rows contain and the 'Operation class: Read' statement reinforces safety. This adds substantial context not available from annotations alone.

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

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

The description is front-loaded with a clear purpose statement and organized into logical paragraphs. It is slightly lengthy but every sentence provides valuable context—no fluff. The inclusion of 'Operation class: Read' is a concise summary despite being redundant with annotations.

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 all essential aspects: return shape (items plus pagination facts), the known missing total count, integration_id sourcing, matched filtering semantics, and hints about potential_company_id. With no output schema, this description adequately prepares the agent for 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 meaning beyond the schema by explaining why integration_id is required (no listing endpoint, found in URL) and the practical use of matched=false for backlog. However, most parameter semantics are already well-documented 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 clearly states the tool's purpose: 'List matchers in Hudu' and explains what a matcher is in detail. It distinguishes itself from siblings by explicitly mentioning hudu_update_matcher for resolution and describing the specific use case of matched: false for sync backlog.

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

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

It gives explicit guidance on when to use the tool: 'The reason to call this is almost always `matched: false`' and directs the user to hudu_update_matcher for resolving unmatched rows. It also clarifies the necessity of integration_id and how to obtain it, providing practical alternatives and 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?

Despite annotations already declaring readOnly and non-destructive, the description adds substantial behavioral context: no paging (returns everything in one response), the meaning of truncated, the absence of total counts, and the significance of page_was_full as the only honest signal. This goes far beyond the structured annotations and prepares the agent for response interpretation.

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 long but every sentence earns its place. It is structured into logical paragraphs: definition, paging behavior, filtering guidance, and return shape. It is front-loaded with the core purpose and uses precise, non-redundant language throughout. No filler or 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 10-parameter list tool with no output schema, the description covers the essential operational facts: no paging, the truncated flag, the lack of total count, the meaning of page_was_full, and the relationship to ip_addresses. It also explains the return shape ('items' plus pagination facts). The description, combined with the rich schema, gives the agent everything needed to use 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 coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema: clarifying that address matches stored CIDR text and does not perform containment search, calling company_id 'the most useful filter here,' and mentioning the fields parameter for keeping large lists small. It doesn't fully compensate for every param, but enriches the most important ones.

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 'List networks in Hudu' and immediately defines what a network is (a CIDR subnet owned by a company). It clearly distinguishes this from related tools by mentioning hudu_list_ip_addresses for viewing allocations inside a network, and the sibling list shows hudu_get_network for a single network. This is a specific verb+resource statement that differentiates from siblings.

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 when-to-use guidance: filter by company_id when working for one customer, and states that address matches stored CIDR text rather than offering containment search. It also directs users to hudu_list_ip_addresses with network_id to see allocations, effectively naming an alternative. The no-paging caveat also tells users how to adapt filters if truncated, which is practical usage guidance.

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