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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description merely states the action without detailing any side effects, permissions, reversibility, or notification behavior. For a mutation tool, this is a significant gap, as the agent cannot infer any constraints or consequences beyond the surface action.

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

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

The description is a single, direct sentence with no extraneous words. It is appropriately sized for a simple mutation operation and is front-loaded with the core action. There is no waste or redundancy.

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

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

For a tool with three parameters, no annotations, and no output schema, the description is too minimal. It does not explain how to identify the issue (through issueId or identifier), whether one is preferred, or any context about the comment's placement. An agent would need additional inference to invoke the tool correctly, making this incomplete.

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

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

Schema coverage is 67% (only 'message' has a description in the schema). The tool description does not add any parameter semantics or clarify how to use 'issueId' vs 'identifier' or whether both are needed. It provides no compensation for the undocumented parameters, leaving the agent to guess the relationship between the two optional identifiers.

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 'Add a comment to an issue' clearly states the verb (add), the object (comment), and the target (issue). It distinguishes the tool from all siblings, as no other sibling handles comments. While it is succinct, it leaves no ambiguity about 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?

The description implies usage: one would use this tool when they want to comment on an issue. It does not explicitly state when to use it versus alternatives, but no sibling tool is available for commenting, so the context is clear. However, it lacks explicit guidance on when not to use it or any prerequisites.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose the side effect (new document), the content format (markdown), and child-document behavior via parentId. It omits the return value, permission requirements, and failure behavior, which are notable gaps for a mutation with no 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 short sentences with no filler. The core purpose is front-loaded, and the optional parentId behavior is placed second without unnecessary detail.

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

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

The description plus fully documented schema is enough to make a valid create call. However, with no output schema and no annotations, missing return-value, permission, and error details leave a clear gap for an agent that needs to use the created document afterward.

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 title, content, parentId, and teamspaceId. The description's parentId hint mostly restates the schema's 'Parent document ID; omit to create a top-level document' rather than adding new semantic 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 opens with a specific verb and resource: 'Create a new document in a teamspace.' It further clarifies markdown content and optional parentId child placement, which clearly separates it from siblings like huly_update_document and huly_delete_document.

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

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

The intended use is implied by 'create a new document' and the parentId guidance, so an agent can tell this is for new documents rather than updates or searches. However, it does not explicitly name alternatives or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns that deletion cannot be undone and instructs the agent to confirm the documentId first, which is critical for a destructive operation. However, it does not mention other behaviors like cascading effects or required permissions, leaving some gaps.

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

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

The description is only two sentences, front-loaded with the action and the most important caveat (irreversibility). Every word earns its place, with no filler or redundancy.

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

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

For a destructive operation with no annotations and no output schema, the description is somewhat thin. It covers the action and the irreversibility warning, but does not specify what happens on success (e.g., return format) or any prerequisites beyond confirming the ID. A bit more context about fallback behavior or failure states would make it complete.

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

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

The schema description coverage is 50% (only the 'confirm' parameter is described in the schema, while 'documentId' is not). The description adds modest context by telling the agent to 'confirm the documentId is correct', which hints at the parameter's purpose but does not add detailed semantics for either parameter. It partially compensates for the schema gap but not fully.

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

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

The description states a specific verb ('Delete') and a specific resource ('a document'), which clearly distinguishes it from sibling tools like huly_get_document or huly_update_document. The purpose is immediately obvious and unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives. The destructive nature implies caution, but there is no guidance on prerequisites (e.g., being certain the document is the intended one) or when not to use it. Usage context is only implied by the action itself.

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

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

With no annotations provided, the description must carry the burden of behavioral disclosure. It does explain that content is stored in a collaborative blob and can only be retrieved through this tool, which is a significant behavioral detail. However, it doesn't disclose the return format beyond markdown default, error conditions, or whether it's a read-only operation (though 'Fetch' implies it). The description adds valuable context but lacks completeness.

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, concise and front-loaded with the core action ('Fetch a document title and its full content by ID'). The second sentence about the collaborative blob adds necessary context without fluff. Slightly verbose but efficient overall, earning a 4 rather than 5 due to minor 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?

Given the tool's simplicity (2 params, no output schema), the description covers the essential: what it does, the default format, and the uniqueness of content retrieval. It lacks details on error handling, authentication, or performance, but for a read tool with clear purpose, it's adequately complete. No output schema means it doesn't need to explain return values, so the description is sufficient.

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

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

Schema description coverage is 50%, with documentId having a basic description but format only having an enum. The description adds meaning for format by explaining markdown is default and content is markdown by default, but doesn't explain the difference between html and markup. It does not elaborate on documentId beyond schema, so it partially compensates for the coverage gap but not fully.

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 'Fetch' and the resource 'document title and its full content by ID', which precisely defines the tool's purpose. It also distinguishes itself from siblings like huly_list_documents by noting it retrieves full content, not just metadata. The mention of markdown by default and the collaborative blob uniqueness sets it apart.

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 the full content of a specific document, contrasting with list/search tools that provide summaries. However, it doesn't explicitly state when not to use it or mention alternatives like huly_get_issue, but the context signals with siblings provide enough guidance. The statement about the collaborative blob implies this is the only way to get content, but 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?

No annotations are provided, so the description carries the full burden. 'Fetch' implies a read operation, but it does not explicitly state it is non-destructive, nor does it disclose error behavior (e.g., if the issue is not found) or any permissions. It does mention return content (description and comments), which adds some context, but leaves behavioral aspects largely implicit.

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 states the core action and key details without any fluff. It efficiently conveys the tool's purpose and identification methods in minimal words.

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

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

For a simple read tool with no output schema and no annotations, the description is decent but incomplete. It mentions the return includes description and comments, but does not clarify that at least one identifier parameter is required (the schema has no required fields), nor does it mention error handling or the exact response format. These are notable gaps for an agent to call it correctly.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description adds little beyond the schema: it restates that either internal ID or human identifier can be used, which is already present in the param descriptions. It does not clarify the constraint that exactly one of the two is needed, or what happens if both are provided.

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 fetches a full issue, with specific identification methods (internal ID or human identifier like PROJ-12). It distinguishes from siblings like huly_list_issues (listing) and huly_comment_issue (commenting) by focusing on retrieval of a single issue with full details.

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

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

The description implies when to use it (to get a full issue) but does not explicitly mention alternatives or exclusions. It does not say 'use this when you need detailed issue info' or contrast with listing tools. The purpose is clear, but guidance on choosing among siblings is only implicit through the tool name and description.

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

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

With no annotations, the description carries the behavioral burden. It discloses the read-only nature ('list'), the absence of content in results, and that ids feed a follow-up fetch. It does not mention pagination behavior, ordering, or the exact response shape beyond ids, which would increase transparency.

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

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

Two sentences with no filler: the first states the core purpose and the second explains both filter modes and the downstream use of returned ids. Everything 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?

Covers the main usage, both filter modes, and the relationship to huly_get_document. Since there is no output schema, the exact fields beyond 'ids' are not stated, and limit-based pagination is not mentioned, but for a simple listing tool the description is close to complete.

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

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

Schema coverage is 67%; parentId and teamspaceId already have descriptive schema text, and the tool description largely paraphrases them, adding little new meaning. The limit parameter has no description, but its default/min/max constraints convey enough; the description does not address it.

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

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

States a specific verb and resource: 'List documents without their content.' It clearly scopes the tool as a metadata-only listing, and the last sentence links returned ids to huly_get_document, implicitly distinguishing it from content retrieval siblings.

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

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

Gives concrete context: filter by teamspaceId for a single space, by parentId for child documents, and it points downstream to huly_get_document. However, it does not contrast with huly_search_documents or state when listing is preferable to searching, so no exclusion guidance is 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?

With no annotations, the description must carry the behavioral burden. It discloses that results include the status name and human identifier, but it does not explicitly state that the operation is read-only, nor does it mention pagination, ordering, or any prerequisites.

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

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

Two short sentences carry all the essential information, with the verb and resource first, the optional filter second, and result details last. There is no redundant or vague wording.

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

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

For a simple list tool with two optional parameters and no output schema, the description covers the core action, the filter, and notable result fields. It leaves out ordering and full result shape, but those are minor for this complexity level.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that projectId is an optional filter, but it does not describe the 'limit' parameter; the schema's default/min/max constraints partially fill that 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 opens with the specific verb 'List' and resource 'issues', and adds an optional 'projectId' filter, making the tool's function immediately clear. It does not explicitly distinguish from sibling tools like huly_get_issue, but the resource and plural verb make the intended use evident.

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 'optionally filtered by projectId' implies that this tool is for retrieving issue collections, possibly scoped to a project. However, it provides no explicit guidance on when to choose this over huly_get_issue or huly_list_projects, leaving the decision to inference.

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

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

With no annotations, the description carries the transparency burden, and the verb 'List' adequately signals a read-only operation with no side effects. It does not disclose pagination, scope (all accessible projects vs. limited), or result format, but none of these are likely to be surprising for a simple zero-parameter listing.

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?

One short sentence with no filler. The operation is front-loaded and the parenthetical earns its place by clarifying the domain concept.

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?

Enough for an agent to decide to call the tool, but with no output schema and no annotations, the description does not say what fields the returned projects include or whether pagination/limiting applies. A note such as 'returns project IDs and names for all accessible projects' would close the remaining gap.

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

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

There are no parameters, so the description cannot add parameter-level meaning beyond the schema; per baseline, zero parameters earn a 4. The 'Tracker projects' clarifier adds useful domain context, which is more than an empty schema provides.

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

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

Description uses a clear verb and resource: 'List Tracker projects', and the parenthetical ('the spaces issues live in') grounds what a project is. It is immediately evident this is not huly_list_issues, but it does not explicitly differentiate from huly_list_teamspaces, so it stops short of a full 5.

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

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

The parenthetical implies usage: if you need the containers that issues live in, this is the list tool, and huly_list_issues is for the issues themselves. However, no sibling or alternative is named, and there is no explicit when-to-use or when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'List all teamspaces' unambiguously signals a read-only operation with no side effects, and the parenthetical adds semantic context about what a teamspace is. Though it doesn't describe response format or pagination, the operation is simple enough that the description is adequately transparent.

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

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

Two sentences with no filler. The core action is stated first, followed by a brief clarifying explanation and the use case. 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 the simplicity of a parameterless list tool with no annotations or output schema, the description covers everything an agent needs: what it does, what a teamspace is, and why the result matters (obtaining a teamspaceId). Nothing essential 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 tool has zero parameters, so there is no parameter semantics to document. The description correctly avoids inventing constraints and stays focused on the operation itself. This is the appropriate baseline for a parameterless tool.

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 'teamspaces' and clarifies their role ('the spaces documents live in'), which immediately distinguishes them from sibling list tools like huly_list_projects and huly_list_documents. An agent can understand exactly what this tool returns without ambiguity.

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

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

The description explicitly states the primary use case: 'You need a teamspaceId from here before creating a document,' giving clear context for when to call this tool. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when this is the right choice among sibling list tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions the performance impact of content search, but omits other behaviors such as case-insensitivity (though that is in the schema), default behavior without searchContent, how results are returned, or any permission requirements. The single behavioral note is insufficient.

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

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

Two sentences with no fluff. The primary purpose is stated first, and the optional behavior is introduced efficiently. 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 the tool has 4 parameters, no output schema, and no annotations, the description is incomplete. It fails to mention the teamspaceId parameter for scoping searches, the limit parameter for pagination control, or what the return format looks like. An agent cannot fully understand the tool's capabilities without inspecting the schema further.

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 describes query as case-insensitive and searchContent as a boolean, but the description adds meaningful context about searchContent's performance implication (each document fetched individually). However, it adds nothing about limit or teamspaceId, which lack schema descriptions, leaving those parameters under-documented. It partially compensates for the 50% schema coverage.

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

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

The description clearly states the verb 'Search' and the resource 'document titles', and distinguishes it from sibling tools like huly_list_documents by implying a keyword-based search rather than a simple listing. It also mentions the optional body search, adding specificity.

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

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

The description provides guidance on when to use searchContent=true (to search bodies) and notes the performance tradeoff, but it does not explicitly state when to use this tool versus alternatives like huly_list_documents or huly_get_document. Usage context is partially implied but not fully clarified.

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

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

With no annotations provided, the description carries the behavioral burden. It clearly discloses the destructive aspect: 'content replaces the entire body,' and warns against naive append attempts. It does not mention permissions or return values, but the main mutation risk is covered.

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

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

Two tight sentences with no filler. The critical replacement behavior is front-loaded, and the append workaround is provided as a short, actionable follow-up.

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 low-complexity mutation tool, the description covers the target, mutable fields, destructive semantics, and the safe append workflow. Since there are no annotations and no output schema, a bit more detail about response or error behavior would be needed for a 5.

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

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

Schema coverage is 67%, and the description adds meaning beyond the schema by explaining the append workflow and reinforcing that content is a full replacement. The documentId role is obvious from the sentence structure, even though it lacks a schema 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?

States a specific verb and resource: 'Update a document title or content.' This clearly differentiates it from sibling tools like create, get, and delete, and the replacement semantics reinforce what the operation 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?

Provides explicit guidance for the common append case: read with huly_get_document, merge, then write back. It does not explicitly state when to prefer create/delete, but the intended update workflow is clear enough.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns account/workspace info and implies a read-only verification, but it does not explicitly state that no data is modified or describe error/authentication-failure behavior. The wording is adequate for a simple whoami tool but could be more explicit.

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

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

Two concise sentences with no filler. The primary purpose is front-loaded, and the usage guidance is integrated efficiently.

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 zero-parameter connection-check tool, the description is complete: it explains what the tool verifies, what it returns, and when to invoke it. No output schema is needed because the return content is described in plain language.

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 there is nothing for the description to clarify. The baseline of 4 applies, and the description appropriately adds no unnecessary parameter details.

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

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

The description states a specific action ('Verify the Huly connection and credentials') and a concrete result ('returning the current account and workspace'). It clearly distinguishes itself from sibling tools like huly_list_documents or huly_get_document by focusing on connection state rather than data 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 gives explicit usage timing: 'Run this first after configuring the server.' It does not explicitly name alternatives or exclusions, but the instruction to run it first establishes its role as a preliminary check relative to all sibling tools.

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