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

The description discloses significant behavioral traits: tag names that don't exist are auto-created at the workspace level, and the Townsquare API has no delete-tag mutation. This goes beyond schema details and warns the agent about potentially irreversible side effects.

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

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

The description is compact and front-loaded with purpose, followed by a crucial warning and a concrete example. Every sentence contributes meaningful information without wasted words.

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

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

For a simple mutation with no output schema, the description covers the core purpose, side effects, and an example. It does not describe return values or error behavior, but given the tool's simplicity and full schema coverage, the description is adequate.

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

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

The input schema already describes all parameters (100% coverage). The description adds a usage note about exact spelling and casing for tagNames and includes an example that clarifies the goalId format, providing value beyond the schema.

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

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

The description opens with a clear action: 'Attach one or more tags to a goal by name.' This specifies the resource (goal) and the method (by name), and it distinguishes the tool from its sibling remove_goal_tags.

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 the usage (to add tags) but does not explicitly reference an alternative such as remove_goal_tags for removal. It provides a caution about auto-created tags and the lack of a delete-tag mutation, which informs when to use it, but this is implied rather than stated as explicit when-to-use guidance.

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

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

With no annotations, the description carries the burden and does well by disclosing the latest-only limitation and API rejection for non-latest IDs. It doesn't mention return values or auth, but the example and limitation details provide solid 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 compact, front-loaded with the core action, and includes a well-placed example. Every sentence is useful, and the structure (limitation, resolution step, rejection behavior, example) is logical and efficient.

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 delete tool with no annotations or output schema, the description provides essential context: the constraint on which update can be deleted, how to obtain the correct ID, and the expected failure mode. This is complete enough for an agent to use the tool 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that goalUpdateId must be the latest update and how to resolve it via get_goal, going beyond the schema's format description. It doesn't cover dryRun, but the schema already does.

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 'Delete the latest goal update on a goal,' using a specific verb and resource while clearly distinguishing from siblings like edit_goal_update and post_goal_update. It explicitly narrows scope to the most recent update, making the 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?

Provides concrete guidance: resolve the update ARI via get_goal (first item in updates list) before calling, and warns that earlier updates cannot be removed. This effectively states when to use the tool and the prerequisite, and implicitly excludes non-latest updates.

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

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

With no annotations provided, the description carries full transparency burden and exceeds it: it discloses partial-update semantics (only supplied fields change), markdown-to-ADF conversion, details-overwrite behavior (and why), and the metricId vs targetId asymmetry. This goes well beyond structured schema 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 well-organized with sections, a code example, and no filler. It is slightly longer than necessary but every sentence adds context about behavior or usage.

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

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

For a 9-parameter tool with nested objects and no output schema, the description covers identification, required fields, partial updates, status/score derivation, markdown handling, details replacement, and metricUpdates schema. It leaves nothing ambiguous for invocation.

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

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

Schema covers 100% of parameters, so baseline is 3; the description adds substantial meaning by explaining why both goalId and goalUpdateId are needed, clarifying that metricUpdates requires metricId rather than targetId, and correcting the schema's ambiguous 'append' note by explicitly stating details replace. This tips the score above baseline.

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

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

The description uses a specific verb 'Edit' with the resource 'goal_update' and lists exact use cases (fix a typo, adjust status/score, correct a metric value, replace body). It clearly distinguishes from sibling tools by referencing 'previously-posted' and comparing to post_goal_update.

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 establishes when to use: for editing an existing update, and contrasts with post_goal_update (the create tool) through status/score rules and metricUpdates asymmetry. It also states the prerequisite that at least one editable field is required. However, it doesn't explicitly name alternative tools for different actions (e.g., update_goal for goal properties).

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

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

No annotations are provided, so the description must carry the transparency burden. It states that it 'Returns complete goal details' and lists included fields, which implies a read-only operation. However, it does not disclose any permissions, potential errors, or side effects. For a simple read, this is adequate but not rich, hence a mid-level score.

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

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

The description is a single, front-loaded sentence: 'Get detailed information about a specific goal by its ID.' It immediately communicates the core action and then efficiently lists what is returned. No filler or redundant content.

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

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

With no output schema, the description appropriately explains the return value by enumerating key fields (description, metrics, parent/child relationships, recent updates). It covers the main purpose sufficiently for a simple get-by-ID tool, though it omits details like error behavior or permissions. Overall, it is complete enough for expected use.

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

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

The input schema has 100% description coverage for the only parameter (goalId), including its ARI format. The tool description merely says 'by its ID' which adds no new meaning beyond the schema. Since the schema already fully documents the parameter, the baseline of 3 is appropriate.

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

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

The description clearly states 'Get detailed information about a specific goal by its ID', using a specific verb ('Get') and resource ('goal') with the distinguishing mechanism ('by its ID'). This separates it from sibling tools like list_goals (listing) and search_goals (searching), and from get_goals (plural) which likely fetches multiple goals.

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 usage when you have a specific goal ID and want complete details. However, it does not explicitly mention when not to use it or name alternatives such as list_goals or search_goals. The 'by its ID' phrasing provides clear context, but no exclusions or alternative references are given.

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

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

With no annotations, the description carries the burden of describing behavior. It discloses what the tool returns (complete goal details, relationships, updates) and that it's batch-oriented, but does not mention error handling for invalid/missing IDs, partial-failure behavior, or auth prerequisites. Basic read behavior is implied but not 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 package the purpose, return value, and efficiency benefit with no filler. Information is front-loaded and every phrase 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 the tool's low complexity (one parameter, no output schema), the description provides adequate context: it states what is fetched, what details are returned, and the advantage over the singular alternative. It could mention edge-case behavior but is otherwise complete for a batch fetch.

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

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

The input schema already provides 100% coverage for the single parameter, including ARI format and maximum count. The description adds no new semantic detail about the parameter itself; its value mainly restates the batch 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 fetches multiple goals by their IDs in a batch request, which distinguishes it from get_goal and list_goals/search_goals. It names the specific resource and operation, and explicitly contrasts with get_goal.

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 guidance: use this when you need multiple goals by known IDs, and it is more efficient than calling get_goal repeatedly. It does not explicitly exclude list_goals or search_goals, but the batch-by-ID purpose implies that distinction.

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

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

No annotations are provided, so the description must carry the burden. It discloses the return value (description, members, linked goals, recent updates), which is transparent for a read operation. It does not mention errors or permissions, but for a simple get, this is acceptable.

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

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

The description is a single, front-loaded sentence that clearly states the action, resource, and key return fields. It is concise and 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?

With one parameter, no output schema, and a simple get operation, the description is complete. It enumerates the return details, providing sufficient context for an agent to anticipate the tool's 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 parameter description is detailed, including the ARI format. The tool description adds no new meaning beyond restating 'by its ID', so the baseline 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 detailed information for a single project by ID, with a specific verb 'Get' and resource 'project'. It distinguishes itself from siblings like list_projects by emphasizing 'specific project' and 'by its ID'.

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

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

The description implies usage when you need complete details for one known project, but it does not explicitly name alternatives or when-not-to-use it. The context is clear enough for an agent to infer the distinction from 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?

With no annotations, the description carries the burden of disclosing behavior. It does state the batch nature and return contents, but lacks mention of error handling for invalid IDs, ordering, or explicit read-only status. 'Fetch' implies safety, but not explicitly stated.

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

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

The description is two sentences with no filler. It front-loads the action and efficiently covers purpose, return details, and rationale for preference.

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

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

For a single-parameter batch read, the description covers the core purpose, expected return content, and efficiency advantage. It lacks edge-case behavior (e.g., partial failures, missing IDs) but is largely complete given the schema's parameter detail and absence of an output schema.

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

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

The input schema fully describes the only parameter (projectIds) with format and max items, so description adds little extra meaning. The phrase 'by their IDs' reinforces but does not enrich beyond the schema, matching the baseline for high 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 specifies a clear verb ('Fetch'), resource ('multiple projects by their IDs'), and scope ('single batch request'). It also distinguishes itself from the sibling tool get_project by highlighting efficiency, making the purpose unambiguous.

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

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

The description explicitly frames when to use this tool over get_project ('More efficient than calling get_project multiple times'), naming the alternative. However, it does not mention exclusions or other siblings like list_projects/search_projects, so it falls short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses what is checked and what is returned (connection status, response time, diagnostics), but does not explicitly state side effects (e.g., read-only), auth requirements for the call itself, or network behavior. Adequate but not rich.

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

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

Two sentences with no filler. The verb is front-loaded, and every clause adds value: what it checks, what it returns, and diagnostic scope.

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

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

The tool is simple with one optional parameter and no output schema. The description covers purpose and return values, which is sufficient for a health-check tool. Could add a note on when to run it, but not necessary for completeness.

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

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

The single parameter 'verbose' is fully described in the schema (100% coverage), so the description adds no new parameter-level meaning. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description uses a specific verb ('Check') with a clear resource ('API connectivity and authentication status') and lists return values. It is immediately distinct from sibling tools that operate on goals/projects.

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 for verifying connectivity and authentication, but does not explicitly reference alternatives or exclusions. Still, the context is unambiguous given the sibling tool set.

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

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

No annotations are provided, so the description carries the burden. It discloses the list behavior and cursor-based pagination, but does not describe the response shape, ordering, or any potential rate limits. For a read-only list tool, this is adequate but not thorough.

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, front-loaded with the primary purpose, and includes all essential capabilities (filtering, pagination) without extraneous 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?

With no output schema, the description covers the key aspects of listing and filtering goals, and mentions pagination which is critical for large result sets. It does not describe the response format, but for a list operation this is acceptable given the schema detail.

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 all five parameters, each with clear descriptions. The description adds context about optional filtering and pagination but does not go beyond the schema details. 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 'List Atlassian Goals' with optional filters by status, search term, or tags, and mentions pagination. This distinguishes it from siblings like get_goal (single goal) and list_projects (different resource).

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

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

The description implies usage for listing/filtering goals and pagination, but does not explicitly contrast it with sibling tools such as search_goals or get_goals. No when-not-to-use 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 carries the full burden. It does disclose cursor-based pagination and optional name filtering, which are useful behavioral traits. However, it omits other characteristics like response shape or any side effects, which a fully transparent description might include.

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 contains no fluff. Every word contributes meaning, making it highly efficient.

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

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

The description covers the main functionality but lacks differentiation from sibling tools like search_projects and does not describe return values (no output schema). For a simple list tool, it is adequate but not fully complete given the ambiguous sibling relationships.

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 offers 100% coverage with descriptions for all three parameters. The description adds minimal value beyond confirming the name filter and mentioning pagination for large sets, which aligns with the baseline for high 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 tool lists Atlassian Projects with optional name filtering. It uses a specific verb and resource, making the purpose evident. However, it does not explicitly differentiate from sibling tools like search_projects or get_projects, which could lead to agent confusion.

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

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

The description implies usage for listing projects and specifically calls out pagination for large result sets, providing clear context. It does not explicitly mention alternatives or when not to use the tool, 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It thoroughly explains the status/score derivation, including the specific band ranges, midpoint scores, and the UI decimal-to-integer translation (e.g., '0.8 → 80'). It also warns about validation errors when combining non-score statuses with a score, and notes the markdown-to-ADF conversion. These are critical behaviors beyond simple 'posts an update'.

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

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

The description is well-structured with bold headers for 'Status and score' and 'Markdown,' plus an example call. It is information-dense but every section contributes to correct usage. It is slightly long given the markdown details, but the complexity of the tool justifies the extra words, and the example is highly practical.

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

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

This is a complex tool with 8 parameters and no output schema. The description covers all critical aspects: how to obtain the required goalId, the nuanced status/score mapping and validation constraints, markdown support, and includes a complete example call. Even though return values are not described, there is no output schema to reference, so the description sufficiently prepares the agent for invocation. Sibling tools are also contextually implied through the 'post' framing.

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

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

The input schema already has 100% parameter description coverage, setting a baseline of 3. The description adds significant semantic layers for the most complex parameters: it explains how score and status interact with band midpoints, provides concrete examples, and clarifies that goalId must be an ARI. While targetDate and metricUpdates rely on their schema descriptions, the overall parameter guidance is enriched meaningfully.

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

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

The description clearly states the tool's purpose: 'Post a weekly status update to a goal — the entry that appears in the goal's Updates tab.' It uses a specific verb ('post') and resource ('goal update'), and distinguishes it from sibling tools like edit_goal_update and delete_latest_goal_update by the 'post' framing. The requirement for an ARI rather than a name further specifies the tool's input.

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 a clear prerequisite: 'Resolve the goal's ARI via search_goals or get_goal first; this tool requires the ID, not a name.' This guides the agent on preparation before invoking the tool. However, it does not explicitly mention alternatives like edit_goal_update for modifying existing updates or delete_latest_goal_update for removing them, so it stops short of an exhaustive when-not-to-use explanation.

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 burden of behavioral disclosure. It explicitly reveals a key side effect: tags are only detached from the goal, and the workspace-level tag definition remains. It also clarifies the lookup behavior for tagNames. This is meaningful transparency beyond a simple restatement, though it omits error behavior and dryRun semantics.

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 plus a focused example. It is front-loaded with the action, and every sentence serves a purpose—clarifying the operation, the parameter preference, and the scope of effect. 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 purpose, side effects, and parameter usage, and the example provides a concrete usage pattern. It does not mention return values or dryRun, but given no output schema and a simple mutation, the core context is sufficiently complete. The sibling list and schema fill in the rest.

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 functional difference between tagNames and tagIds (tagNames looks up IDs from the goal's current tags), and the example illustrates how to pass tagNames. This goes beyond the schema's field-level 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's function: 'Detach one or more tags from a goal.' It uses a specific verb ('detach') and resource ('goal'), and the scoping detail ('Tags are only detached from the goal — the workspace-level tag definition remains') distinguishes it from related tools like add_goal_tags.

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, explicitly preferring tagNames over tagIds and explaining when tagIds is appropriate ('rare case where the caller already has them'). It does not explicitly mention alternatives like add_goal_tags, but the parameter-preference guidance and example give strong contextual direction.

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

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

With no annotations, the description carries the full burden. It thoroughly explains the TQL syntax, supported operators, fields, and provides examples, which effectively communicates the query behavior. It stops short of describing response format or error handling, but for a search tool the core behavior is well disclosed.

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

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

The description is structured with clear sections for operators, fields, and examples. Every sentence carries informative weight, and the use of headers and bullet points makes it scannable. It is appropriately detailed for a query language tool without being redundant.

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 complexity of TQL and the absence of an output schema, the description covers the essential aspects: what can be searched, how to construct queries, and provided examples. It lacks explicit behavior about pagination or result structure, but the schema covers cursor and limit, so the description 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?

Schema coverage is 100%, but the description adds substantial meaning beyond the schema by defining each searchable field, explaining operator usage, and giving concrete query examples. This is significantly more than the schema's terse 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 'Search for goals using TQL' with a specific verb and resource. It distinguishes itself from sibling tools like list_goals by emphasizing flexible, operator-based searching, and from get_goal/get_goals by covering multi-condition queries.

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 extensive context on when to use the tool through operator explanations and multiple examples (e.g., filtering by name, status, owner, tag). It does not explicitly name alternatives or exclusion criteria, but the search-focused language and examples imply it is for filtered queries rather than simple listing.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool supports name-based queries with LIKE and OR operators, and that only the 'name' field is searchable. This provides behavioral constraints beyond just the tool name, although it doesn't explicitly state that the operation is read-only or describe 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 well-structured with clear sections for operators, fields, and examples. It is slightly verbose given the schema already includes examples, but every sentence contributes to understanding the TQL syntax. The first sentence provides immediate clarity.

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 no output schema and no annotations, so the description should explain return values and pagination. It does not mention what the response looks like, that results are paginated, or how the cursor works beyond the schema's mention. While the schema covers cursor and limit, the description is incomplete for a tool with no 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?

Schema description coverage is 100%, so a baseline of 3 applies. The description adds meaning beyond the schema by thoroughly explaining the TQL language, operators, and examples, which helps the agent construct valid searchString values. It also clarifies that queries are name-based only.

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

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

The description clearly states the tool's purpose: 'Search for projects using TQL (Townsquare Query Language)' and goes on to specify the supported operators, searchable fields, and examples. It distinguishes itself from sibling tools like search_goals by focusing on projects and from list_projects by introducing TQL as the search 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 filter projects by name using TQL conditions, providing examples that illustrate the query syntax. It doesn't explicitly mention when not to use it or name alternatives, but the examples and field specification give clear context for typical use cases.

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

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

With no annotations, the description fully carries the burden. It discloses that only supplied fields change (partial update), that markdown is converted to ADF, that archiving is destructive in effect, and that owner takes an Atlassian account ID. These are non-obvious behaviors beyond what the schema states.

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

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

The description is longer than average but front-loaded with purpose, then exclusions, then behaviors, and a helpful example. Every section adds value; the bulleted structure aids scanning. Slightly verbose but earns its space.

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

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

For a mutation tool with 8 parameters, no annotations, and no output schema, the description covers essential context: partial update semantics, exclusions, destructive archive, markdown conversion, owner ID format, and a realistic example. This is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: owner account ID type, destructive archive semantics, markdown conversion, and a concrete example with targetDate structure. Some params like startDate rely on schema alone, but the extra guidance 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 opens with a specific verb and resource: 'Edit a goal's metadata' and enumerates the editable fields. It explicitly distinguishes from sibling tools by stating status changes go through post_goal_update and tag changes via add/remove_goal_tags, making the 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?

Provides explicit when-to-use guidance with named alternatives ('Status changes are NOT done here; use post_goal_update... Tag changes are also separate...'). Also states the requirement of at least one editable field and warns to confirm before archiving, giving clear conditions for use.

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