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

The description discloses permission requirements and a specific rule for projectAdministration:administrator, which adds value beyond the annotation readOnlyHint=false. It doesn't mention side effects like invitations, but those are partially covered in the schema.

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

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

Two sentences, front-loaded with the action, then providing auth and rule 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?

The description covers the core action, auth requirements, and a key constraint. With output schema and full param descriptions, it's fairly complete. Lacks explicit comparison to sibling tools, but that's secondary.

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 a cross-parameter constraint: 'projectAdministration:administrator requires every other granted product to be administrator too.' This clarifies how to correctly set the products parameter beyond the schema.

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

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

The description clearly states 'Add one member to a project with product access, company and roles.' It uses a specific verb and resource, and distinguishing it from siblings that list, update, or remove project 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 provides explicit context on when to use the tool: 'The signed-in user must be a project admin (or account admin).' It also gives a rule about product access consistency. However, it doesn't explicitly mention alternatives or when not to use it, e.g., comparing to acc_import_project_users.

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 declare readOnlyHint=true, and the description does not contradict this. It adds valuable behavioral context: validation is against ISO 19650, ACC's conformingStatus is reported when a naming standard is active, and output includes stats plus non-conforming files with reasons. This goes beyond simple 'read-only' to describe the actual audit behavior.

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

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

The description is two sentences with a trailing phrase, front-loaded with the core purpose ('Audit an ACC folder...'). Every clause contributes: method (folder tree), standard (ISO 19650), special behavior (conformingStatus), return values, and use case. No 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?

There is an output schema (not shown), so return values need not be detailed. The description covers purpose, standard, conditions ('when a naming standard is active'), and use case. Minor gap: does not mention how config_id relates to the audit, but the schema documents that. Complete enough for an audit tool with good annotations.

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

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

Schema description coverage is 100% (all 5 parameters have descriptions). The tool description adds no additional parameter-specific meaning beyond the schema. Baseline for full schema coverage is 3, which is appropriate here.

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: auditing an ACC folder tree for naming compliance against ISO 19650. It distinguishes from siblings like 'acc_validate_names' (which likely validates individual names) by specifying a folder-level audit that returns compliance stats and non-conforming file lists.

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 indicates when to use it: as a routine standards/metadata QA check for daily/weekly CDE review. It does not explicitly mention alternatives or exclusions, but the focus on auditing (rather than validation or configuration) implies the appropriate context relative to sibling tools.

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

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

The readOnlyHint annotation already establishes that this is a read-only operation. The description adds useful behavioral context by listing exactly what is checked (credentials, user session, token cache, region, callback URL) and advising when to call it, which goes beyond the annotation.

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

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

The description is two sentences, front-loaded with the core purpose, followed by a compact enumeration of details and usage advice. There is no wasted wording.

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

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

With no parameters, an output schema, and a description that states what it checks and when to invoke it, the tool is fully contextualized for an agent to select and call correctly. The usage note about calling first and on auth errors completes the picture.

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

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

The tool has zero parameters and the schema coverage is trivially 100%. Per the rubric, a baseline of 4 applies for no parameters, and the description adds sufficient context about what the status inspection covers.

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

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

The description clearly states the tool's purpose with a specific verb ('Check') and a specific resource ('authentication state of the ACC connection'). It also enumerates the exact pieces of state it inspects, making it distinct from sibling tools like acc_login, acc_logout, and acc_whoami.

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 to call this tool 'first in a session, and whenever an auth error occurs,' providing clear usage context. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full 5.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this by stating it 'Returns a JSON structure' and 'review it first, then create,' making it clear the tool does not modify anything. It adds context about the output being a template for later creation and the from_config option, which aligns with and expands on the annotation's safety profile.

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 main purpose, and includes a practical usage hint in the middle. Every sentence earns its place: purpose, output destination, and input options. No redundant or filler content is present.

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 six fully documented parameters and the presence of an output schema, the description covers the essential context: what the tool produces, who it is for ('any project'), how to provide inputs, and the follow-up action (pass to acc_create_folder_structure). The description is complete for a template-generation tool with rich structured metadata.

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 documented in the schema. The description adds some semantic grouping by referencing 'WIP disciplines, Published milestones and Shared subfolders' and mentions from_config with an example, but it does not substantially enrich the parameter meanings beyond what the schema descriptions already provide.

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: 'Generate a generic ISO 19650 CDE folder structure... from simple lists' and distinguishes it from siblings by noting the output is 'ready to pass to acc_create_folder_structure' rather than directly creating folders. This specific verb+resource combination makes the tool's purpose unambiguous and differentiates it from the create-folder sibling.

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

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

The description gives clear usage context: it is project-agnostic and meant for building a folder tree template, with specific instructions on inputs ('Give the WIP disciplines, the Published milestones and the Shared subfolders') or pulling from config. It also implies the alternative workflow by pointing to acc_create_folder_structure for actual creation, though it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral details: values are validated against code tables, and the name can include a -Status-Revision suffix. This goes beyond the annotation's simple read-only signal without contradicting 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 two sentences, front-loaded with the core purpose, and includes a practical usage tip without any wasted words. Every clause carries meaning.

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

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

With a full input schema and an output schema present, the description's job is to provide usage context, which it does well by naming the intended scenario and a prerequisite. The only minor omission is not mentioning limitations or when to prefer a different tool, but this is not critical.

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% parameter coverage, including descriptions and an example for values_json. The description adds only a general note about validation and suffix behavior, which is useful but not essential given the schema's completeness.

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 ('Build') and resource ('correct container ID'), and clearly states it operates on field values validated against code tables, with an optional suffix. This distinguishes it from sibling tools like acc_validate_names, which validates rather than composes.

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 'Use when creating a new deliverable name' and gives a concrete prerequisite: 'check the next free sequence number with acc_search_folder first.' It does not mention alternative tools or when not to use it, but the context is clear.

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

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

With only readOnlyHint=false in annotations, the description adds valuable behavioral context: it creates a 'NEW document' (no overwrite) and explains the API limitation for moves. It does not fully detail side effects like metadata preservation, but it goes beyond what annotations provide.

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

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

Two sentences, front-loaded with the core action, followed by a critical constraint. No filler or repetition. Every sentence adds value.

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

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

Given an output schema exists and all params are documented, the description sufficiently explains the tool's purpose, use case, and a key API limitation. It doesn't explain every edge case (like preserving custom attributes) but is complete for typical usage.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add parameter-specific details, but it reinforces context like 'same project' and 'NEW document'. This meets the baseline for full schema coverage.

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

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

The description uses a specific verb+resource+outcome ('Copy a file version into another folder of the same project as a NEW document') and clearly distinguishes from siblings by mentioning the WIP → Shared/Published hand-off. It is not a tautology and fully conveys what the tool does.

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 when to use it ('typical WIP → Shared / Published hand-off when not using an ACC review workflow') and gives an exclusion/alternative ('when not using an ACC review workflow'). Also clarifies that ACC cannot move items via API, so copy then delete in UI if a move is required.

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

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

Annotations already declare readOnlyHint false, so the write nature is known. The description adds purpose but does not disclose behavioral details like permissions, reversibility, or effects on existing documents. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that communicates the purpose and key usage context without redundancy. It is concise 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?

Given the full schema, output schema, and annotations, the description is adequate for a create tool. It covers the main use case and context. Minor gaps like permissions or prerequisites are not critical given the available structured data.

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

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

Schema description coverage is 100%, so all parameters have meaningful descriptions. The tool description adds overall context but does not introduce new meaning specific to individual parameters beyond what the schema already provides.

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

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

The description clearly states the verb and resource: 'Create a custom attribute definition on a folder.' It also provides context about ISO 19650 metadata fields, which distinguishes it from sibling tools like acc_set_custom_attributes (which sets values) and naming-standard 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 indicates when to use this tool: 'when the ACC file-naming standard is not used or extra fields are needed.' This gives clear context, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations include readOnlyHint: false, indicating a write operation. The description adds useful constraints (single subfolder, requires parent folder) beyond the annotation, but does not discuss permissions or failure behavior.

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

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

Two concise sentences, front-loaded with the primary action, with no wasted words. The alternative is clearly named.

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 create operation with output schema present and full parameter coverage, the description adequately covers usage context and distinguishes from the main sibling. No further details are needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on parameters beyond what the schema already provides, adding no extra meaning.

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

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

The description uses a specific verb ('Create') and resource ('single subfolder under a parent folder'), clearly distinguishing it from the sibling tool acc_create_folder_structure which handles whole CDE trees.

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 the scope ('single subfolder') and directs to an alternative for entire trees ('use acc_create_folder_structure instead'), providing clear when-to-use and when-not-to-use guidance.

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

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

The description discloses key behavioral traits beyond the readOnlyHint=false annotation: idempotency (existing folders reused, safe to re-run) and the return format (URNs level by level). This adds genuine value. It does not cover failure modes or permission requirements, but those are less essential given the other disclosures.

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, each serving a distinct purpose: main action, idempotency safety, and return value. No fluff, front-loaded with the primary action, 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?

Given tool complexity and the existence of an output schema, the description sufficiently covers key aspects: batch creation, idempotency, and return behavior. It does not mention prerequisites like the parent folder existing, but the schema and sibling tool names (e.g., acc_get_top_folders) help fill that gap. Overall, complete enough for selection and invocation.

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

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

Schema description coverage is 100%, so the structured descriptions already document all parameters. The description adds context about the intended use of the 'structure' parameter (ISO 19650 containers) but does not add syntax or format details 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 clearly states the tool creates a whole nested folder tree in one call, with the specific purpose of CDE setup per ISO 19650. This distinguishes it from sibling tools like acc_create_folder (single folder creation) by emphasizing batch/nested structure creation.

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 (CDE setup, creating entire folder trees) and implies it is the batch alternative to repeated acc_create_folder calls. However, it does not explicitly name alternatives or exclusion cases, so it stops short of full '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?

The description goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that product activation is asynchronous, that polling acc_get_project is required, and that adding a project admin triggers member copy from the template. It also reveals the API limitation that location cannot be updated later, which is valuable 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 front-loaded with the core purpose, follows with a concise workflow, and ends with a key caveat. Every sentence earns its place, and the structure with line breaks makes the asynchronous and location-immutability notes easy to parse without being verbose.

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

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

Despite 19 parameters and a complex workflow, the description covers prerequisites (account admin), asynchronous behavior, post-creation steps, and the sole limitation around location updates. Since an output schema exists, return values need not be explained, so the description is complete for agent decision-making.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds meaningful param context: location parameters (latitude/longitude, address) can only be set at creation, and template_project_id cloning is tied to the workflow. It also clarifies that 'Template Project' is used when creating a template, though the schema already mentions this.

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 statement: 'Create an ACC project (optionally cloned from a template)' and positions it as 'the first step of setting up a CDE.' This distinguishes it from sibling tools like acc_get_project and acc_list_projects by focusing on creation and optional template cloning.

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

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

The description explicitly states when to use the tool: the signed-in user must be an account admin, and this is the only place to set location data. It also names alternatives and follow-ups: poll acc_get_project until products are active, then use acc_add_project_user, and change location via the ACC UI since no update endpoint exists.

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 only provide readOnlyHint=false; the description adds context that this tool only initiates the review and does not handle approve/reject decisions, which happen in the UI. This aligns with the readOnlyHint and gives behavioral context beyond the annotation.

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

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

The description is two sentences, front-loaded with the action verb, and contains no redundant information. Every sentence adds value.

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

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

The description covers the tool's role in the workflow, points to monitoring via acc_get_review, and notes the UI for approvals. With an output schema present and full schema parameter coverage, this is adequately complete, though it could mention prerequisites like needing an existing workflow (implied).

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 detailed descriptions for all 5 parameters (e.g., version_urns format). The description adds no additional parameter-level detail, so the baseline of 3 applies.

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

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

The description uses specific verbs 'Start (initiate)' and identifies the resource as 'a document review on an existing approval workflow'. It also clarifies the action as 'submitting containers for the checking/approval transition' and distinguishes from siblings by directing monitoring to acc_get_review.

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 that subsequent approve/reject decisions happen in the ACC UI and that monitoring is done via acc_get_review, which provides clear context for when to use this tool versus alternatives. It does not explicitly list exclusion scenarios, but the guidance is strong.

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 destructiveHint=true, but the description goes beyond by explaining the soft-delete behavior (hidden, restorable) and the need for user confirmation. This adds meaningful behavioral context 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 concise, two sentences, and front-loaded with the core action. Every word adds value, from the soft-delete clarification to the restore pointer and user-confirmation requirement.

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

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

The tool is simple with two well-documented parameters, has an output schema, and annotations indicate destructive behavior. The description covers the key contextual points: soft delete, restoration path, and user confirmation, making it fully complete for this 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% for both parameters (folder_id and project_id), so the schema itself fully documents them. The description adds no additional parameter-specific details, staying at the baseline expected when schema coverage is high.

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

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

The description clearly states the verb 'Delete' and resource 'folder in ACC Docs', and specifies it is a soft delete that hides the folder and can be restored. This distinguishes it from the sibling tool acc_restore_folder and other folder operations.

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

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

The description explicitly says to confirm with the user first and mentions that the folder can be restored via acc_restore_folder, providing clear usage context and an alternative. This helps the agent decide when to use this tool and when to rely on the restore mechanism.

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. The description adds meaningful context by explaining local disk saving behavior and the temporary signed URL mode with a validity window, going beyond what annotations provide.

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

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

The description is a single compact sentence that packs in both main functionality and a key edge case (link_only). It is front-loaded with the action and resource, with no wasted words.

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

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

The tool has good annotations, full schema coverage, and an output schema. The description covers the two primary modes of operation and the temporary URL timeout, which is sufficient for an agent to select and invoke it correctly. Minor gaps like overlapping item_id/version_id usage are already evident from the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the link_only parameter's behavior (returns a temporary URL) and referencing the dest_path as 'local disk', which goes beyond the schema descriptions.

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

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

The description clearly states the tool downloads a document from ACC Docs to local disk or returns a temporary signed URL. This is a specific verb+resource pairing that distinguishes it from siblings like acc_upload_file or acc_copy_file.

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

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

The description implies usage (use this to download files), but it doesn't explicitly state when to use this versus alternatives or mention any exclusions. Context from sibling names helps but isn't spelled out in the description.

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

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

Annotations provide readOnlyHint: true, and the description aligns by using 'Batch-read'. Beyond the annotation, the description adds useful behavioral context: it details the exact metadata categories (including review workflows and custom attributes) and notes the batch capability. Since the annotation already establishes safety, the added value is enough for a 4, though it does not go into rate limits or pagination.

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

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

Two sentences, front-loaded with the core action. The first sentence lists what is read and the second gives the use case. No filler or repetition of schema field names in an unstructured way. Every word earns its place.

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

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

Given readOnlyHint, full schema coverage, and an output schema, the description covers the essential aspects: what it does, what it returns, and when to use it. It is a simple batch read operation, so no further pitfalls or prerequisites need disclosure. The description is complete for an agent to select and 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?

Schema description coverage is 100%: both parameters have clear descriptions (project_id and urns, with note about item vs version URN resolution). The tool description adds no extra parameter-level detail, so it does not need to compensate. Baseline 3 is appropriate given the schema already documents parameters thoroughly.

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: 'Batch-read document metadata', then enumerates the exact fields returned (title, revision number, process state, review/approval status, custom attribute values). It also calls it 'the daily status-checking tool for a CDE manager', which clearly positions it against sibling tools like acc_get_item or acc_list_reviews.

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 the primary use case ('daily status-checking tool') and what it returns, giving an agent a good sense of when to invoke it. However, it does not explicitly name alternative tools to use instead in other scenarios, nor does it mention exclusions (e.g., when to use acc_get_item or acc_list_reviews 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?

The annotations already declare readOnlyHint=true, and the description adds useful behavioral context: it explains that permission levels are named only when they match a standard ACC level, and that inheritance is disclosed. This goes beyond the bare read-only annotation without contradicting 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 a single, compact sentence that efficiently conveys the core functionality and key output attributes. No wasted words, and the most important verb ('List') 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?

Given the simple parameter set and the presence of an output schema, the description adequately covers what the tool returns. The only minor gap is that the phrase 'standard ACC level' is not elaborated, but this is a domain detail rather than a critical omission.

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 descriptions for both parameters (Folder URN, Project id) with 100% coverage. The description does not add further parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists who can access a folder, and the specific aspects covered (users/roles/companies, permission level, direct/inherited). This distinguishes it from sibling tools like acc_set_folder_permissions and acc_remove_folder_permissions, which are write operations.

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

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

The intended use is implied by the verb 'list' and the resource (folder permissions), but there is no explicit guidance on when to choose this tool over alternatives or any exclusions. It does not mention prerequisites like authentication, but the context is reasonably 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?

Annotations already declare readOnlyHint=true, and the description's 'Get' aligns with that. The description adds context about the returned data (tip version, process/review state), but does not disclose additional behavioral traits such as error handling, permission requirements, or rate limits. With annotations covering the read-only safety profile, the added context is moderately useful.

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

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

The description is a single, tightly constructed sentence that front-loads the action and resource, then lists key output fields. No wasted words; every part is informative.

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

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

For a simple read-only lookup with only two parameters and an existing output schema, the description provides adequate context about the tool's purpose and the data returned. It doesn't cover edge cases or error conditions, but these are not essential for a straightforward get 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?

Both parameters (project_id, item_id) are fully described in the schema with 100% coverage. The description does not add parameter-level semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves a file's info and its current (tip) version, listing specific fields (version number, size, file type, etc.). The verb 'Get' and the resource 'file's info and current version' are specific, and this differentiates from siblings like acc_list_item_versions (which lists all versions) and acc_get_docs_metadata (which may return document metadata).

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 no guidance on when to use this tool versus alternatives. It does not mention scenarios, exclusions, or how it compares to sibling tools like acc_list_item_versions or acc_get_docs_metadata. The usage context is only implied by the description itself, but no explicit alternatives are provided.

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 explicitly states 'Read-only' and adds that the standard is configured in the ACC Docs UI, beyond what the readOnlyHint annotation provides. It clarifies that no modifications are possible and where the actual settings live, giving useful 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?

Two compact sentences, each earning its place. The first specifies core function and returned elements; the second adds the read-only note, configuration location, and a typical use case. No redundancy or 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?

With an output schema present, the description need not detail return values. It covers the tool's read-only behavior, the source of the standard, and a practical application. For a simple getter with two clear parameters, this is 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%, with both hub_id and project_id having straightforward descriptions. The tool description does not add any parameter-specific meaning beyond the schema, justifying 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 opens with 'Read the ACC file-naming standard configured on the project', a specific verb+resource pair. It further explains the ISO 19650 naming enforcement and lists the exact data returned (delimiter, fields, metadata codes), making the purpose unmistakable and distinct 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?

Provides a clear application context: 'Useful for cross-checking against the project BEP convention.' This tells the agent when to use the tool, but it does not explicitly mention alternatives or exclusion criteria, so it stops short of a 5.

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

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

Annotations provide readOnlyHint: true, and the description adds useful behavioral context: the tool returns per-product activation statuses that transition to 'active' after creation. This goes beyond the annotation by explaining the polling use case, though it does not detail additional response behaviors (handled by output schema).

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

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

Two concise sentences, front-loaded with the primary function and followed by a usage hint. No fluff or redundancy.

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

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

The tool has a simple parameter set, an output schema (so return values are handled), and clear annotations. The description fully specifies the tool's role in the workflow—checking activation after project creation—making it complete for selection and invocation.

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

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

Schema description coverage is 100%, with both parameters already described in the schema (account_id as speed-up hint, project_id with GUID format). The description adds no new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Get') and resource ('one project's details') and specifies the scope (per-product activation status). It distinguishes itself from sibling tools by focusing on detailed retrieval for a single project after creation, distinct from listing or item-level tools.

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

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

The description explicitly says 'Use after acc_create_project' to check activation status, providing a clear context for when to use it. It does not mention alternatives or exclusions, but the guidance is specific and actionable.

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

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

The readOnlyHint annotation already declares the tool is read-only, but the description adds valuable context by noting that approve/reject decisions cannot be made via API and that the tool is intended for monitoring and chasing. This provides a behavioral nuance beyond the annotation, clarifying what the tool cannot do and its practical purpose.

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

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

The description is only two sentences, with the primary purpose front-loaded and the additional behavioral note in the second sentence. Every word earns its place, and there is no redundant content or 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?

Given that the tool has an output schema (not shown but present) and a read-only annotation, the description sufficiently covers what the tool does and its key limitation (no decisions via API). It lacks details about error handling or edge cases, but for a single-item retrieval tool with optional flags and a rich output schema, the description is adequately complete.

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

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

The input schema provides 100% description coverage for all four parameters, so the schema already documents each parameter's meaning. The description does not add new semantic detail beyond the schema (e.g., it mentions 'optionally the files' which maps to include_files, but the schema already states this). With high schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('one review's detail'), then enumerates the exact data returned (status, current step, due date, per-step progress, optional files). This distinguishes it from sibling list tools like acc_list_reviews, which return collections rather than a single item's detail.

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 ('use this to monitor and chase') and provides an exclusion ('step decisions can only be made in the ACC UI, not via API'). While it does not name an alternative tool for listing reviews, the phrase 'one review's detail' implicitly differentiates from list tools, offering clear context without explicit sibling naming.

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

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

Annotations already provide readOnlyHint=true, and the description adds non-trivial behavioral details: it returns folder URNs and reveals namingStandardIds when a naming standard is active. This gives the agent useful expectations about the output beyond the annotation.

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

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

Two sentences: the first states the core action, the second explains purpose and an additional output detail. No wasted words, front-loaded with the key verb.

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

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

The tool is simple, has an output schema, and readOnlyHint=true. The description covers the primary purpose, usage context, and an extra return-value detail (namingStandardIds), which is sufficient for an agent to use it safely and effectively.

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

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

The input schema fully documents both hub_id and project_id (100% coverage). The description adds no additional parameter-level meaning beyond what the schema already 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 function: 'Get the root-level folders of a project' with specific examples. It distinguishes from siblings by emphasizing root-level scope and positioning it as the entry point before listing/creating subfolders.

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

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

Explicitly advises 'Start here to obtain folder URNs before listing or creating subfolders,' giving a clear use case. It does not name alternative tools directly, but the sequencing guidance is strong enough to prevent 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?

The description discloses the asynchronous nature ("asynchronous server job") and the batch limit (200 members), which are important behavioral traits beyond the readOnlyHint annotation. It does not contradict annotations. Missing details like failure handling or partial success, but the annotation already indicates mutation, and the async disclosure adds significant value.

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

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

Two concise sentences with the key information front-loaded. No wasted words, and the async note is efficiently placed in parentheses.

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 bulk async operation, the description covers the essentials: what it does, scale, and async behavior. An output schema is present, so return values are likely documented elsewhere. It could mention job status tracking or error scenarios, but the description is adequate for a tool 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 description coverage is 100%, and the users_json parameter is already well-documented with structure and defaults. The description adds minimal extra parameter context (just "from a list"). Baseline of 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the tool's action: "Bulk-add up to 200 members to a project in one call." This uses a specific verb and resource, and the scope (bulk vs. single) distinguishes it from the sibling tool acc_add_project_user. The title also reinforces 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 gives a clear use case: "Good for mobilizing a full project team from a list." This implies it's for bulk operations, implicitly contrasting with single-user tools like acc_add_project_user. However, it does not explicitly state when not to use it or name alternatives, so a small deduction.

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

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

Annotations already provide readOnlyHint=true, and the description adds contextual purpose (source of companyId) but does not disclose additional behavioral traits such as pagination behavior, error cases, or data volume. The description does not contradict the annotation, and the added context is modest.

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

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

The description is a single sentence that front-loads the primary action and purpose. Every word earns its place, with no redundancy 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 list operation with a readOnlyHint annotation and an output schema present, the description captures the essential purpose and downstream use. It doesn't explain return format (handled by output schema) or pagination explicitly, but the schema defaults provide that. Overall, adequate for the tool's complexity.

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

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

Schema description coverage is only 50%, with account_id and name_contains described, while limit and offset are not. The description itself does not explain any parameter semantics; it only mentions companyId as an output. This fails to compensate for the schema gaps.

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

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

The description clearly states the tool lists companies (partners) registered in the account, using a specific verb and resource. It also distinguishes itself from sibling list tools (e.g., acc_list_hubs, acc_list_projects) by explaining its unique role as the source of companyId for member additions and COMPANY folder permissions.

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

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

The description implies when to use the tool: when a companyId is needed for adding members or granting COMPANY folder permissions. This provides context for selection among siblings, though it does not explicitly name alternatives or specify when not to use it.

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

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

With readOnlyHint=true indicating a safe read operation, the description adds valuable context beyond annotations: it explains the difference in output between folder-level and project-level views, including the namingStandardIds binding. It doesn't mention pagination or output format, but the output schema covers returns, and no destructive behavior is implied.

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, using three sentences to convey the core operation, the two modes, and the additional naming-standard binding detail. Every sentence earns its place 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?

Given the two-parameter schema, readOnlyHint annotation, and output schema presence, the description is fully complete. It explains the critical distinction between folder and project views, and since an output schema exists, detailed return values are unnecessary 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?

While the schema already includes descriptions for both parameters, the description adds deeper semantic meaning by explaining how the presence or absence of folder_id changes the scope and data returned. This goes beyond the schema's 'Folder URN' and 'Project id' by clarifying the behavioral impact.

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

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

The description clearly states the tool lists custom attribute definitions and specifies the key attributes returned (id, name, type, allowed values). It distinguishes between the folder-level and project-level variants, making it distinct from sibling tools like acc_create_custom_attribute and acc_set_custom_attributes.

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

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

The description provides clear context on when to use each mode: with folder_id for folder-level views (BIM 360 + ACC), without for the ACC project-level registry. It doesn't explicitly name alternatives or exclusions, but the guidance on parameter choice is 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?

Annotations declare readOnlyHint=true, covering safety. The description adds useful context about the returned contents (tip-version info, process/review state, naming conformingStatus), but does not mention pagination behavior or hidden entries, which are left to the schema.

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

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

Single sentence leads with the action and lists specific output details. No wasted words, perfectly sized.

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

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

With an output schema and readOnly annotation, the description provides sufficient detail about what is returned. However, it does not explicitly note that results are paginated or that hidden entries are excluded unless include_hidden is set, which are important for invocation. Overall 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?

Description does not add meaning to any parameters. Schema covers 67% of parameters with descriptions, but missing descriptions for page_limit and page_number are left to defaults/ranges. The description does not compensate for these gaps or clarify parameter usage.

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

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

Description uses specific verb 'List' and resource 'contents of a folder', and details what is included (subfolders, files, tip-version info). This clearly distinguishes from siblings like acc_get_item or acc_search_folder.

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

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

No explicit guidance on when to use this tool versus alternatives. The description simply states what it does; there is no mention of when to prefer this over acc_search_folder or acc_list_item_versions. Usage context is implied but not stated.

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

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

Annotations provide readOnlyHint=true, and the description does not contradict this. It adds useful context beyond annotations: results depend on current credentials, and it clarifies the accountId format (without 'b.'), which is a common pitfall. It does not mention pagination or potential errors, but for a simple list operation this is adequate.

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

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

The description is two concise sentences, front-loaded with the main action and immediately clarifying key details. Every word earns its place, with no redundancy or unnecessary 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 no-parameter list tool with an output schema, the description fully covers what the tool does, what it returns, and a critical detail about the accountId format. It also implies authentication via 'current credentials,' which is sufficient given the tool's simplicity.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per guidelines, 0 params yields a baseline of 4. The description does not need to explain inputs, but it does provide relevant output context (account ids, data region), which is beneficial.

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

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

The description clearly states the tool lists ACC/BIM 360 hubs (accounts) visible to current credentials, including account IDs and data region. This specific verb+resource+scope distinguishes it from sibling tools like acc_list_projects, and the accountId detail adds precision.

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

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

The description implies a clear use case by noting that the accountId (without 'b.') is what project-administration tools need, guiding users to invoke this tool as a prerequisite. It does not explicitly mention alternative tools or when not to use it, but the context is sufficient for most scenarios.

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

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

The annotations already declare readOnlyHint: true, so the safety profile is known. The description adds the audit trail context beyond the annotation, but does not discuss pagination, ordering, or any other behavioral traits. This adds some value but is not rich.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the action, resource, and a relevant industry context (ISO 19650) economically.

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

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

For a read-only list operation with an output schema present, the description is adequate. It covers the purpose and context, while pagination is left to the schema. No critical information appears missing, though it could mention pagination explicitly.

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 describes 'item_id' and 'project_id' but leaves 'page_limit' and 'page_number' without descriptions. The tool description does not add any parameter-level semantics, so it relies on self-explanatory names and the existing schema descriptions. Since coverage is 50%, it meets the baseline but doesn't enhance understanding.

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

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

The description uses the specific verb 'List' with the resource 'version history of a file', and clarifies the audit trail content ('who uploaded which version when'). This clearly distinguishes it from sibling file tools like acc_get_item or acc_upload_file.

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 mentions the ISO 19650 traceability requirement, implying the appropriate context for use, but does not explicitly state when to use this tool over alternatives or when not to use it. Therefore, it provides clear context without 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral context: it is the newest API (implying version/recommendation), supports filters and pagination (behavioral detail), and provides a template-discovery use case. No contradictions with annotations, and it enriches beyond the annotation 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 two sentences: the first front-loads the core purpose with a specific verb and resource, and the second adds a targeted use case. No wasted words, all sentences earn their place.

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

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

For a read-only list tool with an output schema and rich annotations, the description is complete. It covers the main listing use case, pagination/filter existence, and the template discovery workflow. The schema handles parameter details and output, so no major 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 71%, with limit/offset lacking descriptions. The description adds meaningful semantics for classification (use template to discover project templates) and mentions filters generally, which helps interpret the status/platform/name_contains filters. However, pagination params are not elaborated beyond schema defaults, so it doesn't fully compensate for the missing parameter descriptions.

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

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

The description clearly states the tool lists projects of an ACC account (hub) and specifies it uses the newest API with filters and pagination. It distinguishes from siblings like acc_get_project (single project) and acc_list_hubs (hubs) by explicitly scoping to projects, and adds a distinct use case for discovering templates.

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

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

The description provides clear usage context: list projects with filtering/pagination, and specifically mentions using classification='template' to discover project templates for acc_create_project. It implies when to use this tool over get/create operations but doesn't explicitly state when not to use it or name alternatives, so it's not a full when/when-not guide.

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 the description adds meaningful behavioral context by mapping the output fields ('id', 'autodeskId', 'roleIds') to their use in permission workflows. It does not contradict the annotations and provides extra value beyond the structured data.

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

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

The description is two sentences, front-loaded with the core purpose, and the second sentence adds crucial output semantics without redundancy. Every word earns its place.

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

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

The description is sufficient for a read-only list tool with an output schema. It explains the significance of key output fields and their relationship to other tools, but does not mention pagination or filter behavior. Given the complexity (6 parameters, output schema), it is mostly complete but has minor gaps.

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

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

Schema description coverage is 67%, with the filter parameters described in the schema. The description does not explain the pagination parameters (limit/offset) or add semantics beyond the schema. It links output IDs to permissions but not input parameters, so it does not compensate for the coverage gap.

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

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

The description uses the specific verb 'List' with a clear resource ('members of a project') and enumerates the returned fields (company, roles, access levels, product access). This distinguishes it from siblings like acc_list_projects or acc_get_project.

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: it explains that the returned IDs are used by folder-permission tools and that roleIds are relevant for ROLE-based permissions. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, covering the safety profile. The description adds context about what reviews are and the OPEN filter example, but does not mention pagination behavior or response format. With annotations present, this is acceptable but not rich.

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

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

A single, front-loaded sentence with no wasted words. It efficiently states the verb, resource, scope, and an example use case.

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

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

Given the output schema exists and readOnlyHint is present, the description captures the core purpose and a common scenario. It does not explain all filters, but the schema handles that. Adequate for a list operation.

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

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

Schema covers status and workflow_id filters with descriptions; description clarifies project scope and gives an OPEN example. However, it does not add meaning for limit/offset, and the 60% schema coverage leaves some gap.

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

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

States clearly it lists document reviews (approval processes) in a project, with an explicit example of OPEN reviews. This distinguishes it from siblings like acc_get_review (single review) and acc_create_review.

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 a clear use case ('daily CDE follow-up') and mentions filtering by status (OPEN), but does not explicitly name alternatives or when-not-to-use. The context is clear, just lacking 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?

Annotations already declare readOnlyHint=true, and the description aligns with that. It adds useful context about the workflow scope (WIP→Shared→Published transitions) and notes that create tools may not cover every option, clarifying that the tool only reflects current configuration.

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 focused, front-loaded sentences. Every sentence adds value: the first defines the action, the second provides domain context, and the third explains the practical purpose. 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?

The description is complete for a read-only listing tool: it states what is listed, why the tool exists (workflowId for reviews), and how it relates to creation. With an output schema present and annotations indicating safe read-only behavior, no further detail is needed.

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 descriptions for project_id and active_only with 100% coverage. The description does not add parameter-specific meaning beyond what the schema offers, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists document approval workflows with specific detail (steps, reviewers, status labels, copy destination). It distinguishes from related review tools by emphasizing the workflowId needed to start a review and ties it to the ISO 19650 CDE controlled transitions.

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 workflows are created in the ACC UI and that this tool shows existing configurations and provides the workflowId for starting a review. This gives clear context for when to use it, though it does not explicitly list when not to use or name alternative tools directly.

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?

Goes well beyond annotations: describes non-blocking browser launch, always returning the authorization URL, callback port listening, token exchange and storage, the 45-second cap, the 'still waiting' response, and the 15-day session expiry. This rich behavioral context is critical for an agent to understand the async nature of the tool.

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

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

The description is a single paragraph but covers many essential behaviors. It is front-loaded with the core purpose and then logically walks through the flow, wait behavior, and expiry. Some minor repetition (e.g., '~45 s' and 'capped per call') could be tightened, but every sentence adds useful information.

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

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

For an OAuth tool with async browser interaction, the description fully covers what an agent needs: how to initiate, how to handle the wait/retry, and when to re-run. An output schema exists, so return-value details are not required. The description is complete despite 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 already documents all three parameters at 100% coverage. The description adds operational meaning: wait_only=true for polling, wait_seconds capped per call, and force_login behavior (prompt=login). This contextualizes the parameters without restating the schema text.

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 'Sign in with an Autodesk account (3-legged OAuth with PKCE)', a specific verb+resource pairing that clearly states the tool's function. It distinguishes from sibling auth tools like acc_logout and acc_auth_status by focusing on the login flow.

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

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

Provides clear context on when to use the tool: to start an OAuth flow or re-authenticate after a 15-day expiry. It also gives explicit polling instructions ('call acc_login again with wait_only=true') when the wait times out. No explicit alternatives are named, but the guidance is sufficient for an agent to act.

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 context beyond the minimal annotations (readOnlyHint: false) by specifying exactly what is discarded (refresh token) and the 3-legged session. This is consistent with the non-read-only annotation, and no contradictions exist.

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

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

The description is two sentences, front-loaded with the action, and every word earns its place. It is succinct 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 zero-parameter tool with an output schema, the description fully covers purpose, usage context, and behavioral effect. 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 tool has zero parameters, so the description needs no param details. Per the rubric, 0 parameters defaults to a baseline score of 4, and the description adds no unnecessary parameter context.

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

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

The description clearly states the tool discards the stored 3-legged session (refresh token), using a specific verb and resource. It distinguishes from siblings like acc_login (which creates a session) and acc_auth_status (which checks status).

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 before switching Autodesk accounts' and 'sign in again with acc_login'. This provides a clear when-to-use and names an alternative tool, satisfying the top criterion.

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 only supply readOnlyHint:false, so the description adds meaningful behavioral context: contents move with the folder, direct permissions move while inherited permissions re-derive from the new parent, and re-checking with acc_get_folder_permissions is recommended. This goes beyond the annotations without contradicting them.

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

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

Two compact sentences: the first names the action and scope, the second conveys an important behavioral caveat. No filler or redundant wording.

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

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

The tool has an output schema, and all parameters are documented in the schema. The description supplies the critical behavioral nuance about folder contents and permission handling. While it omits edge-case constraints like moving into a descendant folder, the provided information is 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?

All three parameters have schema descriptions with 100% coverage, so the schema already documents project_id, folder_id, and new_parent_folder_id. The description adds no new parameter-level detail beyond reinforcing the new parent concept, keeping this at the baseline.

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

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

States a clear, specific verb and resource: 'Move a folder (with its contents) under another parent folder.' This distinguishes it from sibling operations like acc_rename_folder, acc_delete_folder, or acc_copy_file, which have different purposes.

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

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

The description implies usage through its purpose statement, but it does not explicitly state when to use this tool versus alternatives like acc_copy_file or acc_create_folder_structure. The permission re-check note provides follow-up guidance, but not tool-selection boundaries.

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, but the description adds substantial behavioral context: it explains how projects add their own naming convention JSON files in ~/.acc-mcp/naming, that without config_id it lists conventions and the current default, and that with config_id it returns full convention details including code tables, status codes, and CDE structure. This goes well beyond the read-only hint, with no contradiction.

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

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

The description is front-loaded with the core purpose in the first sentence, then expands into relevant details about bundled presets, custom config file location, and return behavior. It is a bit lengthy for a tool with one optional parameter, but each sentence adds meaningful information, so it earns its 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?

For a simple listing tool with one optional parameter and a readOnly annotation, the description is exceptionally complete. It covers the default preset, custom config mechanism, file path, selection methods, and what returns when config_id is supplied. The output schema exists, so it need not describe return structure, and the description fully covers usage and behavior.

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

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

Schema coverage is 100% and the config_id parameter is already described as showing full detail. The description reinforces this by explaining 'With config_id, returns the full convention...' and additionally contextualizes how config_id is used in selecting the convention (via ACC_MCP_NAMING_CONFIG). This adds useful usage context beyond the schema's bare 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 opens with a specific verb 'List' and resource 'container-ID naming conventions', and additionally mentions returning the current default. It clearly distinguishes the tool's listing behavior from other ACC tools like acc_get_naming_standard by focusing on available conventions and optional config_id detail.

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 the tool (to list conventions) and how to use the config_id parameter to get full details. It also describes how custom configs are added and selected via config_id or environment variable, which implies usage in a project setup context. However, it does not explicitly compare against sibling tools like acc_get_naming_standard.

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

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

Annotations already declare destructiveHint=true, but the description adds crucial context: it removes only DIRECT permissions, inherited ones persist, project admins are protected, and user confirmation is required. This goes beyond the annotations by describing the exact scope and limitations of the destructive action, helping the agent anticipate outcomes and handle edge cases.

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 tight and front-loaded: the first sentence states the core action, followed by two sentences that address scope and constraints. Every sentence adds necessary information without redundancy or 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?

Given the tool's moderate complexity, an output schema exists, and annotations cover destructiveness, the description provides comprehensive context: what the tool does, what it doesn't do (inherited permissions), its limits (project admins), and a required user confirmation step. This is sufficient for an agent to invoke it appropriately without needing to inspect the output schema.

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

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

The input schema has 100% description coverage: folder_id is 'Folder URN', project_id is 'Project id', and subjects_json explains the JSON array format with an example. The tool description itself does not add parameter details, but with high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Remove all DIRECT permissions of the given subjects on a folder.' It specifies the resource (folder), the subject scope (given subjects), and the permission scope (DIRECT), distinguishing it from sibling tools like acc_set_folder_permissions or acc_get_folder_permissions. The distinction between direct and inherited permissions further clarifies its unique role.

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: it notes that inherited permissions are not affected and instructs to remove them at the parent if full revocation is needed. It also states an exclusion ('Project admins cannot be removed') and mandates user confirmation. This gives clear when-to-use and when-not-to-use guidance relative to 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 destructiveHint=true, but the description adds essential nuance: the member's data/history remains, only access is revoked. It also states the need for user confirmation, giving the agent clear behavioral expectations beyond the annotation flags.

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

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

Two short, purposeful sentences. The main action is front-loaded, and the second sentence adds crucial safety context without waste.

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

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

For a simple tool with two well-documented parameters, an output schema, and annotations, the description fully covers purpose, effect, and safety. 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 input schema already provides 100% description coverage for both parameters (user, project_id), so the description does not add parameter-specific semantics. 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?

Description clearly states 'Remove a member from a project' with a specific verb and resource. It further clarifies the effect (data/history stays, access revoked), distinguishing this from deletion or other 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?

Provides clear context on when to use the tool (removing a member) and includes a safety directive to confirm with the user. It does not explicitly list alternatives, but sibling names like acc_add_project_user make the intended use obvious.

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 annotation readOnlyHint=false already communicates that this is a write operation, and the description adds valuable context by clarifying that contents and permissions are unaffected. This addresses the most likely user concern for a rename operation, though it does not discuss potential failure modes or authentication requirements.

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

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

The description is a single clear sentence that is front-loaded with the action. Every word earns its place, and the parenthetical is concise and informative.

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 rename operation with an output schema present and annotations covering the safety profile, the description is nearly complete. It conveys the primary behavior and side effects, though it omits any note about error conditions or name uniqueness constraints, which are not essential for this low-complexity tool.

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

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

The description does not elaborate on the parameters, but the schema already provides descriptions for folder_id and project_id, covering two of three parameters. The remaining parameter, new_name, is self-explanatory from its title and the tool's purpose, so the description adds little beyond the schema.

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

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

The description uses a specific verb and resource ('Rename a folder'), making the tool's purpose immediately clear. The parenthetical 'contents and permissions unaffected' adds a useful scope qualifier that distinguishes it from sibling tools like acc_move_folder or acc_delete_folder.

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 no explicit guidance on when to use this tool versus alternatives such as acc_move_folder, acc_create_folder, or acc_delete_folder. While the verb 'rename' implies usage, the tool does not state any context, exclusions, or alternative references.

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 readOnlyHint=false annotation already signals a mutating operation, and the description adds the context that the folder is hidden. It does not disclose side effects (e.g., restoring contents, permissions) or any requirements, but it also does not contradict 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 a single, front-loaded sentence that conveys the essential action without unnecessary words. Every word earns its place.

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

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

For a simple restore operation with two well-described parameters and an output schema, the description is mostly sufficient. It could be slightly richer by noting that the folder becomes visible again or that it restores to its original location, but the current text adequately conveys the core function.

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

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

Schema description coverage is 100%, with both folder_id and project_id clearly described as 'Folder URN' and 'Project id'. The description adds no additional meaning beyond the schema, which already fully documents the parameters.

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

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

The description uses the specific verb 'Restore' with the resource 'folder', and specifies 'previously deleted (hidden)' to clarify the exact target. This clearly distinguishes it from sibling tools like delete, create, or rename.

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

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

The phrase 'previously deleted (hidden) folder' implies the primary use case: undoing a deletion. However, it does not explicitly state when to use it vs. alternatives, nor does it mention any prerequisites or exclusions (e.g., folder must be in hidden state).

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

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

Annotations already provide readOnlyHint=true, so the read-only nature is covered. The description adds that the search is recursive and matches exact name/type, and that it returns 'tip versions with their item (lineage) URNs,' but it does not disclose behaviors like pagination limits or performance characteristics. 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?

Two sentences, zero wasted words. The main purpose is stated first, followed by key output detail. It is appropriately front-loaded and concise.

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

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

The tool has an output schema, readOnlyHint annotation, and 80% parameter description coverage. The description covers the core purpose, recursive behavior, exact matching, and output type. Minor gaps remain (e.g., page_number semantics) but are not critical given the schema. Overall, it is complete enough for 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?

Schema description coverage is 80% (4 of 5 parameters have descriptions). The description reinforces the meaning of name and file_type via 'exact name and/or type' and clarifies folder_id as recursive. However, page_number is not described in the schema or description, and the description adds no syntax-level detail beyond the schema.

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

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

The description uses a specific verb and resource: 'Search recursively under a folder for files by exact name and/or type.' It clearly distinguishes itself from sibling tools like acc_list_folder (which likely lists folder contents without recursive search or exact matching) by specifying the scope and method.

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

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

The description implies usage: when you need to find files recursively by exact name or type. However, it does not explicitly mention when not to use this tool or suggest alternatives (e.g., acc_list_folder for listing all files). The context is clear but lacks exclusions or alternative references.

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, so the write nature is known. The description adds meaningful behavioral context: attribute names are resolved against folder definitions, and unknown names are reported with available options, which helps the agent anticipate error handling. It doesn't over-elaborate side effects, but adds useful behavior beyond annotations.

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

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

The description is two sentences, leads with the core action, and each clause adds value—examples, resolution behavior, and error reporting. 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?

Given the output schema exists, annotations are present, and the schema covers all 4 parameters, the description is complete enough. It explains the tool's purpose, gives real-world use cases, and notes error behavior. No critical 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 parameters are fully documented in the schema. The description adds some value by explaining resolution behavior and giving domain examples, but it doesn't significantly go beyond what the schema already provides.

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

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

The description uses a specific verb+resource: 'Set custom attribute values on a document version' and provides concrete examples (moving S2 to S3, stamping Revision, filling Uniclass). It clearly distinguishes from sibling tools like acc_list_custom_attributes and acc_create_custom_attribute.

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 examples give clear usage context ('e.g. move a container... stamp the Revision... fill the Uniclass classification'), and the mention of attribute name resolution implies when to use this tool. It doesn't explicitly name alternatives or exclusions, but the context is strong enough.

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

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

Beyond the annotation (readOnlyHint: false), the description adds meaningful behavior: automatic batch-create for new subjects and batch-update for subjects with existing permissions, plus the CONTROL permission requirement. This is valuable operational context an agent cannot infer from the annotation 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?

Two sentences with a clear hierarchy: primary action, explanatory example, automatic behavior, and prerequisite. No filler or redundant content. Every sentence carries operational value.

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

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

The description covers purpose, usage context, prerequisite, and automatic behavior, which is strong for a permission-setting tool. The output schema supplies return-value details, though the description could be slightly ambiguous about whether existing permissions for unlisted subjects are preserved or cleared. Overall, it is nearly 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 already covers all 5 parameters with descriptions (100% coverage). The description adds real-world examples that clarify the level parameter (e.g., 'upload' vs 'view_download') and shows how subjects_json should be structured via roles and companies. This elevates it above the baseline of 3.

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

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

The description opens with a specific verb+resource: 'Grant or change folder permissions for users, roles or companies'. It provides concrete ISO 19650 examples ('give the design team upload on WIP') and clearly differentiates from sibling tools by emphasizing it is the access-control step, unlike acc_get_folder_permissions or acc_remove_folder_permissions.

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 establishes when to use the tool via the ISO 19650 CDE setup context and gives a clear prerequisite ('Requires CONTROL permission'). It does not explicitly name alternatives, but the wording implies this is for granting/changing rather than getting/removing, so context is clear though exclusions are not stated.

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

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

The description discloses the automatic email-to-user-id resolution behavior, which is valuable beyond the sparse annotations (readOnlyHint: false). It also implicitly confirms the mutation nature. However, it does not mention potential side effects like role_ids replacing existing roles, though that is covered in the schema. No contradiction with annotations 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 two concise sentences with the main purpose front-loaded. It contains no filler or redundant information, making it efficient and easy to parse.

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

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

Given the full schema coverage, the presence of an output schema, and the clear description, the context is sufficiently complete for an agent to select and invoke the tool. The description could additionally mention side effects or permissions, but these are partially addressed by the schema and annotations, so the overall package is strong.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description adds the behavioral detail that email is resolved automatically, which enhances understanding of the 'user' parameter beyond the schema's type enumeration. It also summarizes the parameters, but mostly mirrors the schema, giving only modest additional semantic value.

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 'Change' and clearly identifies the resource ('a project member') and the scope ('company, roles or product access'). It distinguishes itself from sibling tools like acc_add_project_user and acc_remove_project_user by focusing on modifying an existing member, 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 clearly implies use when you need to update an existing project member's attributes, and the email resolution note adds practical context. However, it does not explicitly mention exclusions or alternatives (e.g., when to use acc_add_project_user instead), so it lacks the explicit when-to-use vs. when-not-to-use guidance that would earn a 5.

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

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

Beyond the readOnlyHint=false annotation, the description discloses critical behavior: if the file exists, a new version is added rather than a duplicate, and it mentions chunked S3 upload for large files. This adds value beyond the annotation, though it doesn't cover authentication 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 description is two sentences plus a tip, front-loaded with the primary action and behavior. The versioning detail and large-file note are concise and necessary. No wasted words.

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

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

The tool has an output schema (context signal), so return values need not be described. The description covers crucial behavioral nuances (version vs new doc, chunked upload) and references a prerequisite naming check, making it sufficiently complete for 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 coverage is 100%, so each parameter already has a description. The tool description doesn't add parameter-specific meaning beyond what the schema provides, but the versioning behavior clarifies the effect of the 'name' parameter when conflicts occur. 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 'Upload a local file to an ACC Docs folder' and specifies the key behavior of versioning when a file with the same name exists. This distinguishes it from sibling tools like download_file, copy_file, or create_folder.

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 guidance to validate the name against the project naming convention before uploading, referencing acc_validate_names. It does not explicitly state when not to use the tool, but the upload context is clear and the tip provides a strong usage recommendation.

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

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

With readOnlyHint=true already indicating a safe read operation, the description adds value by explaining the optional -Status-Revision suffix and field-by-field decoding behavior. It does not contradict the annotation and gives insight into how validation is performed.

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

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

Two sentences deliver purpose, specifics, and usage context with zero waste. The core action is front-loaded, making it immediately scannable.

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

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

The presence of an output schema covers return values, and the description covers purpose, usage, and parameter format specifics. The tool's complexity is moderate, and the description leaves no significant gaps beyond what already exists in structured fields.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful detail for the 'names' parameter (suffix format, example) beyond the schema, while 'config_id' is adequately covered by the schema itself. This compensates and elevates the 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 verb 'Validate' and the resource 'file / information-container names' against the project's ISO 19650 naming convention. It distinguishes itself from siblings like acc_compose_name and acc_audit_folder_naming by focusing on validation with decoding, errors, and suggestions.

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 usage context: 'Use before uploading or when checking a delivery list.' While it doesn't explicitly name alternatives, it clearly indicates when to use the tool. This meets the criteria for clear context even without explicit 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?

Beyond the readOnlyHint annotation, the description discloses that the tool requires 3-legged credentials and shows what the current credentials can see. This adds useful behavioral context about authentication and scoping, which the annotation alone does not 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: two sentences, with the first stating the function and the second providing the use case. No unnecessary words 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 simple zero-parameter tool with an output schema and read-only annotation, the description fully covers what the tool does, why it is useful, and when to use it. No gaps in 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?

With zero parameters, the schema fully covers parameter semantics. The description adds no parameter details, but none are needed. The baseline of 4 for zero-parameter tools 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 with a specific verb ('Show') and resource ('signed-in Autodesk user and ACC hubs'), and distinguishes it from sibling tools like acc_list_hubs by emphasizing the credential-scoped view. The mention of fetching hub ids for admin tools further clarifies its role.

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

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

The description gives clear context for when to use it ('verify access after login' and 'fetch hub ids for admin tools'), but does not explicitly mention alternatives or when not to use it. This is clear usage context without exclusions, aligning with a score of 4.

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