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

With no annotations provided, the description carries the full burden. It describes the tool's primary behavior (typeahead search and gid resolution) but does not disclose any additional behavioral traits such as rate limits, stale data warnings, or that only approximate matches may be returned.

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-worded sentence that conveys the tool's unique value proposition concisely. There is no wasted text, and it is immediately clear what the tool does and why it matters.

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 (a typeahead search with no output schema), the description is appropriately complete. It clearly explains the tool's role in the broader workflow of using other Asana tools. A slight deduction because it doesn't hint at the return format of the gid, but that is minor for a search-type tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by framing the tool's overall purpose as turning names into gids, which contextualizes all parameters. It does not add new details per-parameter beyond the schema, but with full coverage, a baseline of 3 is reasonable; the clear purpose statement elevates it to a 4.

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

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

The description uses a specific verb-resource structure ('typeahead search') and clearly distinguishes the tool's unique purpose: converting a human-readable name into a machine-readable gid needed by other tools. It directly addresses the core value of this tool versus its siblings, many of which operate on gids.

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 tool is for looking up gids from names seen in the UI, and the workspace_gid parameter schema adds context for using the tool to find its own input. However, it doesn't explicitly state when not to use it or name alternatives for finding specific resources.

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 returns 'enum_options with their gids' and implies a read-only behavior, which is helpful. However, it doesn't state whether the tool is destructive, requires authentication scopes, or has rate limits. The behavioral disclosure is adequate but not comprehensive for a tool that could be used in multiple scopes.

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 wasted words. The first sentence covers the three scopes precisely, and the second sentence adds critical downstream context. Every sentence serves a purpose.

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

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

Given that there are only three optional parameters (no required ones) and no output schema, the description is fairly complete. It explains the output (enum_options with GIDs) and why it matters. The only minor gap is clarifying what happens when no parameter is provided (possibly a default workspace or error) and whether the output format has any pagination or limits, but these are less critical 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?

Schema description coverage is 100% and each parameter has a clear inline description. The tool's description reinforces that these parameters are mutually exclusive scopes (workspace, project, portfolio) and adds the crucial context that enum_options from the output feed into other dropdown tools. This goes beyond the schema by explaining why you would choose one parameter over another and what the output is used for.

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 specifies the verb 'list' and the resource 'custom fields', and distinguishes three scopes (workspace, project, portfolio). It also adds context about what is returned ('enum_options with their gids') and why that matters ('the input for every dropdown tool'), making the tool's output purpose immediately useful and differentiable from sibling tools like custom_field_create or custom_field_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?

The description implies that the tool is used to retrieve custom fields and enum options needed as inputs for other tools, which provides clear context for when to use it. However, it does not explicitly state when NOT to use it vs alternatives (e.g., when to use asana_find instead, or when you already have the GIDs), nor does it mention that the three parameters are mutually exclusive or if providing none defaults to a specific behavior.

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

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

With no annotations, the description must disclose behavioral traits. It states the tool returns 'authenticated user and their workspaces' and hints at being read-only, but does not detail response format, authentication requirements, or potential side effects. Some context is provided, but more specificity would elevate clarity.

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. Front-loaded with the primary purpose followed by actionable guidance. Every word earns its place.

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

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

Given no annotations, output schema, or parameters, the description is mostly complete. It explains what the tool does and why it matters. Minor gaps: could mention the response includes user ID and workspace details, or explicitly state it's a safe read operation.

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

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

The tool has no parameters (schema coverage 100% automatically). The description adds semantic value beyond the empty schema by explaining what the output represents ('authenticated user and their workspaces') and its practical use (providing workspace_gid).

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

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

The description explicitly states 'authenticated user and their workspaces' and adds usage context ('Call this first'). It clearly differentiates itself from sibling tools like project_create or member_list by indicating it provides the workspace_gid needed for create 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 clear guidance: 'Call this first — almost every create call needs a workspace_gid.' This tells the agent when to use the tool and its purpose. It does not explicitly state when not to use it (e.g., if workspace_gid already known), but the positive 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool makes a field 'available' but does not explain side effects (e.g., whether re-attachment is allowed, permission requirements, or impact if the field is already attached). These gaps leave an AI agent uncertain about the operation's 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 a single, well-formed sentence that conveys the core functionality immediately. There is no redundancy or filler; 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 tool with 6 parameters, a required one, and no output schema, the description is too sparse. It does not explain the logical relationship between project_gid and portfolio_gid (e.g., that one is required, or what happens if both are given). It also omits what the result looks like, leaving the agent without a complete 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?

Schema coverage is 100%, so the baseline is 3. Each parameter has a clear description in the schema (e.g., 'Asana gid, use asana_find'). The tool description adds no extra meaning beyond the schema, but it also does not contradict or confuse. It adequately supports the schema.

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

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

The description clearly states the action: attaching an existing custom field to a project or portfolio. The verb 'attach' and resource 'custom field' are specific, and it is easily distinguished from sibling tools like 'custom_field_create' (creates new fields) or 'asana_list_custom_fields' (lists fields).

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

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

The description provides no guidance on when to use this tool versus alternatives. For instance, it does not explain that this tool is for attaching an already-existing field, while 'custom_field_create' is for creating a new one. No when-not or context cues are given.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states 'Create a workspace custom field' without mentioning side effects, permissions, rate limits, idempotency, or what happens on invalid input. The guidance on dropdown types is helpful but insufficient for a mutation tool with no 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 long, front-loaded with the core purpose, and every sentence adds value. The first sentence states the action, the second provides critical guidance for dropdown types. No wasted words.

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

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

With 6 parameters, no output schema, and no annotations, the description is too minimal. It does not explain return values, error handling, how to use the created custom field, or that types other than dropdown do not need enum_options. The schema covers some parameters, but the overall context is incomplete for a tool of this complexity.

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

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

Schema description coverage is 50%, so the description adds some value by clarifying that dropdown types require enum_options and explaining 'enum' vs 'multi_enum'. However, it does not elaborate on other parameters like name, type (beyond the enum), description, precision, or workspace_gid, which have limited or no schema descriptions. The description provides marginal improvement over the schema.

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

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

The description clearly states the action ('Create a workspace custom field') and the resource ('custom field'). It distinguishes from sibling tools like custom_field_update by being a create operation. The additional guidance on dropdown types adds specificity, though it doesn't explicitly contrast with other create 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 provides specific guidance on when to use 'enum' or 'multi_enum' types and to pass enum_options for dropdowns. However, it lacks explicit instructions on when not to use this tool, such as when to use enum_option_create instead, or prerequisites like workspace ownership.

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 behavioral burden. It correctly indicates the tool modifies name/description but does not disclose whether the operation is idempotent, reversible, or what side effects occur (e.g., dependent items). This is minimally adequate for a straightforward 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?

Two sentences: first delivers core purpose, second redirects related functionality. No redundancy. Every word earns its place, and the description is front-loaded with the primary action.

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 field-update tool with 3 parameters and no output schema, the description is largely complete. It defines what is changed and what is not. The schema already covers how to obtain the GID. Missing a hint about the return value (e.g., 'returns the updated field') but this is minor 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?

Schema coverage is 33% (only custom_field_gid described). The description adds that name and description are the updatable fields, which matches the schema properties. It does not provide constraints (e.g., max length) or formatting rules, so the agent gains little beyond knowing that those parameters exist.

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 'Change a custom field's name or description', specifying the exact verb and resource. It also distinguishes itself from sibling enum_option_* tools by noting that enum values are edited with those, eliminating any ambiguity about scope.

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

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

The description explicitly directs the agent to use enum_option_* tools for editing enum values, which is a clear when-not-to-use. However, it does not mention prerequisites (e.g., field must exist) or when to prefer this over custom_field_create.

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 positioning behavior ('appended at the end unless you give a position'), but with no annotations provided, it should also cover potential destructiveness, required permissions, or side effects. It partially fulfills the behavioral disclosure burden.

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

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

Two short sentences with no wasted words. The core action is front-loaded, and the important positioning detail follows immediately. Every sentence serves a purpose.

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

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

Given 5 parameters, no output schema, and no annotations, the description covers the primary behavior and positioning nuance. However, it omits return value information (e.g., what is returned on success) and any required permissions or side effects. Adequate but not fully complete for confident agent 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 baseline is 3. The description adds minimal parameter context by mentioning position behavior (relating to insert_after/insert_before), but does not explain 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 action ('Add a value') and the target resource ('enum / multi_enum custom field'), distinguishing it from sibling tools like enum_option_update and enum_option_reorder.

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 (when you need to add a dropdown value) but does not provide explicit guidance on alternatives (e.g., using enum_option_update to modify existing options) or exclusion criteria. No when-not guidance is given.

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

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

With no annotations provided, the description carries the full burden of behavioral transparency. It accurately states that the tool moves a value, but does not disclose whether the operation is reversible, whether it triggers side effects (e.g., on dependent views), or if specific permissions are required. The description is correct but minimal for a mutation 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, clear sentence with no wasted words. It is front-loaded with the primary action ('Move an existing dropdown value') and immediately communicates the tool's core function. 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 absence of an output schema and annotations, the description is adequate for a straightforward move operation with 4 parameters. However, it lacks information on return behavior (e.g., confirmation, updated order), error conditions (e.g., invalid position), or constraints (e.g., whether both before/after can be specified). It feels slightly incomplete for a mutation tool of this complexity.

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

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

The input schema has 100% coverage, so baseline is 3. The description adds value beyond the schema by summarizing the operation's parameters ('Move an existing dropdown value') and implicitly clarifying the role of 'after_enum_option' and 'before_enum_option' as positioning parameters. However, it does not explain the mutual exclusivity or optionality of these positioning params, which could cause misuse.

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 ('Move') and clearly identifies the resource ('dropdown value') and the operation context ('within its custom field'). This directly distinguishes it from siblings like 'enum_option_create' or 'enum_option_update', which serve 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?

No guidance is provided on when to use this tool versus alternatives like 'enum_option_update' (which might also affect options) or the other reorder tools (e.g., 'section_reorder'). No prerequisites or exclusions are mentioned, leaving the agent to infer the correct context from the name and siblings alone.

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 bears the full burden of behavioral disclosure. It transparently explains the irreversible effect of disabling (tasks keep the value, hidden from picker) and implies mutation for rename/recolor. It could further detail side effects or response format, but the key behavior 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?

The description is extremely concise at two sentences, with all information front-loaded. It states the purpose first, then the critical behavioral nuance. Every word earns its place; 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 tool has 4 parameters and no output schema, the description is somewhat incomplete. It explains the main effects but does not describe the return value, error conditions, or prerequisites (e.g., that the enum_option_gid must be valid). The description is adequate but leaves gaps for a complete understanding.

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 high (75%), so the baseline is 3. The main description adds little beyond what the schema already provides for the parameters; it mentions 'rename, recolor, or disable' which maps to name, color, and enabled but does not explain enum_option_gid. The schema itself includes descriptions for most 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 clearly states the tool can rename, recolor, or disable a dropdown value. It differentiates from sibling tools like enum_option_create (create) and enum_option_reorder (reorder) by noting the unique 'no delete' behavior and the use of enabled:false to retire a value.

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 (modifying an existing dropdown value) and includes a key guideline about disabling. However, it does not explicitly contrast with sibling tools or state when not to use it, relying on the sibling list for 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?

Since no annotations are provided, the description carries full burden. It transparently discloses the constraint that projects can only have admin/editor/commenter access levels (no view-only), and portfolios can have admin/editor/viewer. This goes beyond the schema to explain behavioral limits of the API. It does not, however, mention other behaviors like whether the tool overwrites existing access or adds incrementally.

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 paragraph with a clear note. Every sentence provides distinct value: the first states the purpose, the note details API 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?

Given the tool has no output schema and moderately simple parameters, the description is complete enough. It covers purpose, constraints, and parameter guidance. The only gap is missing mention of what happens upon a successful or failed add (e.g., response format), but for a member addition tool, the context provided is sufficient for most use cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by stating 'Use asana_find with type user' for the member_gid parameter, providing a sibling tool reference. However, it does not elaborate further on the parent_gid parameter beyond what the schema says. The access_level description is also somewhat redundant with the schema. Overall adds some helpful context but not extensive.

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 'Give a person or team access to a project or portfolio', using specific verb ('add') and resource ('member to project or portfolio'). It distinguishes itself from sibling tools like 'asana_find' (which is for finding entities, not adding) and 'portfolio_add_item' (which adds items, not members).

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 context about when to use this tool vs alternatives, mentioning Asana's own limits on access levels for projects and portfolios. However, it does not explicitly state when NOT to use this tool or mention alternative tools for other scenarios (e.g., removing members, which would be another 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention side effects, authentication requirements, rate limits, pagination behavior, or what 'access level' values look like. For a list operation, this 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?

The description is extremely concise—a single, front-loaded phrase that directly answers the core question. Every word earns its place, with no fluff or repetition of the title.

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

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

Given the lack of an output schema and the tool's simple interface, the description should clarify the return format (e.g., list of members, fields included) and any pagination or default behavior. It does not, leaving the agent with an incomplete mental model of the tool's output.

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 the parameter parent_gid already fully documented in the input schema (including hint to use asana_find). The tool description adds no additional parameter 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 'Who currently has access, and at what level' combined with the title 'List members of a project or portfolio' clearly identifies the tool's purpose: retrieving members and their access levels. This differentiates it from sibling tools like member_add (which adds members) and asana_whoami (which shows the current user).

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like member_add or asana_whoami. It does not mention contexts where another tool would be more appropriate, nor does it provide any exclusion criteria or 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 full burden. It discloses the key behavioral trait that adding an already present item moves it to the specified position. However, it does not mention permissions, error handling, idempotency nuances, or response behavior, 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?

Two sentences with no wasted words. The first sentence states the core action and optionality, the second adds the critical duplicate behavior. Each sentence earns its place.

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

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

Given no output schema or annotations, the description adequately covers the main operation and the duplicate scenario. It could be more thorough about success/failure responses or prerequisites, but the 100% schema coverage compensates partially.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no significant parameter detail beyond the schema; it only implies the optional positioning but does not elaborate on format or constraints of insert_after/insert_before.

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 'Add' and identifies the resource as 'a project (or sub-portfolio) to a portfolio'. It also clarifies the optional positioning and the duplicate behavior, which distinguishes it from sibling tools like portfolio_remove_item and portfolio_list_items.

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 tool's function (adding items to a portfolio) and implicitly distinguishes it from siblings by focusing on addition. However, it does not explicitly provide when-to-use or when-not-to guidance or name 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?

With no annotations provided, the description must fully disclose behavioral traits. It only states the creation action without mentioning idempotency, side effects (e.g., does it overwrite an existing portfolio with the same name?), return values (e.g., does it return the new portfolio's ID?), or permission requirements. This is inadequate for a mutation 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 very concise with a single sentence, and it is front-loaded with the verb 'Create' and resource 'portfolio.' It earns its place by being succinct, though it could benefit from slightly more detail without losing conciseness.

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

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

Given the tool's complexity (4 parameters, no output schema, mutation), the description is too sparse. It does not explain what the tool returns (e.g., the created portfolio object), nor does it clarify that workspace_gid is required. With no output schema and no annotations, the description should compensate with more detail about behavior and return values.

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 75%, and the description adds minimal semantic value beyond the schema. It does not explain the 'color' parameter's format or default, nor does it clarify that 'public' defaults to false (already in schema). The 'workspace_gid' description in the schema provides helpful context (use asana_find), but the tool description itself adds nothing. Baseline is 3 due to high coverage, but the lack of added value drops it to 2.

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 'Create a portfolio in a workspace,' which provides a clear verb and resource, distinguishing it from sibling tools like portfolio_update. However, it does not clarify that the portfolio is created in Asana (the workspace context is implied) and could be more specific about the resource type.

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

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

The description implies usage context by saying 'in a workspace,' and the required workspace_gid and name parameters guide the agent on what to provide. However, there is no explicit guidance on when to use this tool versus creating a project (project_create) or updating a portfolio (portfolio_update), nor any mention of prerequisites like workspace existence.

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 present, so the description must carry the full burden. It adds only one behavioral trait: items are returned 'in their current display order.' It does not state that the operation is read-only, idempotent, or safe. Missing details on permissions, side effects, pagination, or error behavior. The description is insufficient for a mutation-free list operation.

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

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

The description is very short (12 words), but it is a noun phrase fragment rather than a complete sentence. While concise, it is not front-loaded with a clear action or structured for quick scanning. It could be more effective with a verb-first sentence.

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

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

Given the tool has one parameter, no output schema, and no annotations, the description is too minimal. It does not specify that the output is a list, what each item contains (project vs portfolio), handling of invalid inputs, or any pagination. For a simple list tool, the agent still requires more contextual cues to invoke it correctly.

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

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

Schema coverage for the single parameter portfolio_gid is 100% (the schema includes a description). The tool description adds no additional meaning about the parameter. Per guidelines, high schema coverage sets a baseline of 3, and the description contributes nothing beyond that.

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 is a noun phrase ('The projects/portfolios inside a portfolio...') rather than an explicit action statement. The title 'List portfolio items' implies the action, but the description itself lacks a verb defining what the tool does. It is not completely clear that this tool returns a list of items, and it does not distinguish itself from siblings like portfolio_add_item or portfolio_remove_item.

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

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

No guidance is provided on when to use this tool versus alternatives. There are siblings like portfolio_add_item, portfolio_remove_item, asana_find, and others, but the description offers no comparison or context for choice. The agent is left to infer usage from the tool name alone.

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 an important behavioral side effect ('drops any portfolio-level custom field values'), which is helpful since no annotations are provided. However, it does not mention other behavioral aspects like required permissions, irreversibility, or error conditions.

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, both informative and without any superfluous words. It is front-loaded with the primary action and then adds the key side effect.

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 removal tool with no output schema, the description is largely complete: it covers the action, resource, and a notable side effect. It could be improved by specifying what happens on failure, but overall it provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The tool description does not add any new meaning beyond what the schema provides (e.g., no hints about validation or defaults). 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 action ('remove a project from a portfolio') and the specific resource being acted upon. It also differentiates itself from sibling tools like 'portfolio_add_item' by using opposite verb and mentioning side effects.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., when not to use it, or how it differs from other removal or update operations). The description assumes the agent knows the context without explaining trade-offs or 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 full burden. It discloses partial update behavior ('Only the fields you pass are touched'), which is valuable. However, it omits other behavioral traits such as required permissions, idempotency, or side effects. The disclosure is helpful but incomplete.

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-load the purpose and add a critical behavioral detail. Every word earns its place with no redundancy.

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

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

The tool has 4 parameters, no output schema, and no annotations. The description explains what the tool does and the update semantics, but it does not mention what the tool returns (e.g., success indicator or updated portfolio). Given the complexity, this is a moderate 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?

The description adds meaning beyond the input schema by mapping 'visibility' to the 'public' parameter, which the schema only describes with type 'boolean'. It also clarifies that only passed fields are updated. This compensates for the schema's lack of description for the 'public' field (schema coverage 75%).

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 changes a portfolio's name, color, or visibility. The verb 'change' and resource 'portfolio' set a clear purpose. While it doesn't explicitly distinguish from siblings like portfolio_create, the intent is obvious given the sibling context.

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 modifying an existing portfolio, but it does not provide explicit guidance on when to use this tool versus alternatives like portfolio_create. The context of sibling tools makes the usage scenario inferable, but not directly 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?

With no annotations provided, the description must fully disclose behavioral traits. It only reveals that team_gid is required in an organizational context, but omits details on permissions, return value, side effects, or whether the operation is safely reversible. The description is insufficient for an agent to fully understand the tool's behavior.

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

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

The description is a single, front-loaded sentence with no unnecessary words. Every part adds value, making it highly efficient for an AI agent 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?

Despite having 7 parameters and no output schema, the description is very sparse. It lacks information about what happens after creation, return format, error conditions, or relationships to other resources. An agent would need additional reasoning or tool introspection to use this tool correctly in complex workflows.

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

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

The schema covers 71% of parameters with descriptions. The tool description adds critical context that team_gid is conditionally required ('in an organization'), which is not indicated in the schema where team_gid is optional. This goes beyond what the schema provides and aids correct invocation.

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

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

The description clearly states the action 'Create a project' and the resource 'in a workspace', with a specific condition about team_gid in an organization. While the name itself is distinct, it does not explicitly differentiate from sibling tools like project_update or project_duplicate.

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 the tool (creating a project) and a conditional requirement for team_gid in an organization. However, it does not provide guidance on when not to use it or mention alternatives among the 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 full burden. It discloses that the operation returns a job and finishes asynchronously, and clarifies which elements are always copied vs optional. It does not mention whether the original project is modified (assumed safe), auth needs, or rate limits. Decent coverage but not exhaustive.

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

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

Three sentences, each earned: purpose, automatic content, special usage note, and asynchronous behavior. Front-loaded with the verb 'Copy a project'. No redundant words, 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?

For a tool with 4 parameters, no output schema, and no annotations, the description covers purpose, key constraints (always-copied items), optional parameters, and async job response. It could mention that the original project remains unchanged and how to poll the job, but given the complexity, it's sufficiently complete.

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

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

Schema coverage is 100% with good descriptions. The description adds context: it explains that the 'include' parameter adds optional elements beyond the always-carried-over ones, and clarifies the return type (job). This goes beyond the schema's 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 states 'Copy a project' with specific details: tasks, views, and rules are always carried over. It distinguishes from siblings like project_create (which creates blank projects) by noting this is the only way to get a preconfigured Dashboard. Clear verb+resource+unique behavior.

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 the tool is the only way to give a new project a preconfigured Dashboard, providing a strong use case. It lists always-carried-over elements but does not explicitly state when to avoid it or mention alternatives (e.g., project_create for a blank project). Context signals from sibling tools help, but the description could be more explicit.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states the output is 'in display order' and provides gids, indicating a read operation. However, it does not explicitly confirm the tool is read-only, safe, or describe the exact return format (e.g., whether it returns section names or only gids). The description is adequate but could be more 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?

The description is very short and to the point – one sentence with two clauses. It is efficient and avoids fluff. However, it could be slightly improved by front-loading an action verb ('Lists sections...') rather than starting with a noun phrase. Still, it 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 one-parameter list tool with no output schema or annotations, the description is mostly complete. It covers purpose, output order, and a hint about the return value (gids). However, it does not fully describe the output format (e.g., whether it returns just gids or objects with names), leaving some ambiguity. Given the simplicity, a score of 3 is appropriate.

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

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

Schema coverage is 100% for the single parameter, with a detailed description already in the schema. The tool description does not add any additional parameter semantics beyond what the schema provides. Baseline is 3 because the schema already covers it well.

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

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

The title 'List project sections' and description 'Sections of a project in display order' clearly indicate the tool lists sections of a project. It also distinguishes from sibling tools like section_reorder by specifying the output is gids needed for reordering. However, the description lacks an explicit verb like 'list' or 'get' in the text, relying on the title.

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

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

The description implies usage context by stating the output is needed for section_reorder, but it does not explicitly state when to use this tool versus alternatives (e.g., section_create, section_update). No when-not-to-use guidance is provided. The context is implied but not clearly stated.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. While it lists the mutable fields, it does not indicate whether the tool overwrites all fields at once, whether partial updates are allowed, what happens to unspecified fields, or if there are any side effects (e.g., triggering notifications). The 'archived' parameter is mentioned but not explained as potentially destructive.

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 covering the main purpose efficiently. It could be slightly more structured, but it lacks any fluff. A small improvement would be to order fields by importance or include usage guidance without expanding verbosity.

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 lack of annotations, output schema, and low schema parameter coverage, the description is insufficient for an agent to use this tool confidently. It does not state what the response contains (e.g., the updated project object), nor does it warn about permissions or side effects. The tool modifies potentially sensitive fields like 'archived' and 'public', and missing guidance could lead to unintended consequences.

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 low (29%), and the description adds no information beyond the parameter names. For a 7-parameter tool, the description offers no new meaning for 'public', 'notes', or 'archived' which lack schema descriptions. The coverage gap is not compensated, but the schema itself describes 'color' and 'default_view' adequately, and 'project_gid' is well-documented in the schema.

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

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

The description clearly states the tool changes project attributes such as name, notes, color, default view, or archived state. It effectively distinguishes it as an update tool from creation or duplication siblings like project_create or project_duplicate, but does not explicitly differentiate from portfolio_update or custom_field_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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., user must own or have permission on the project), nor does it suggest scenarios where sibling tools like section_update or enum_option_update would be more appropriate.

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

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

With no annotations provided, the description carries full responsibility but only states the basic operation. It omits details like permission requirements, idempotency, error conditions (e.g., duplicate names), or whether the mutation is reversible, leaving significant behavioral 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 a single sentence with no filler words, directly conveying the essential action and optional behavior. Every word earns its place, making it highly 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 absence of output schema and annotations, the description should disclose more behavioral context such as whether the section is appended by default, how position conflicts are resolved, or the response structure. The current description is too sparse for a create operation.

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

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

The description adds no parameter details beyond the schema, but the phrase 'optionally at a chosen position' alludes to the insert_after/insert_before parameters. Schema coverage is 75%, so the baseline of 3 is appropriate; the missing name parameter description is not compensated.

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 'Add' and resource 'section to a project', directly matching the tool's name and purpose. It also mentions optional positioning, which distinguishes it from sibling tools like section_update or section_reorder.

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 main description implies its use when creating a section, but does not explicitly compare to alternatives like section_update or project_list_sections. However, the parameter description for project_gid hints at a workflow using asana_find, providing some contextual guidance.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as the effect on other sections' ordering, whether the operation is atomic, side effects, error cases (e.g., invalid gid), or if the operation can be undone. The description lacks crucial context for a mutation 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, concise sentence that front-loads the purpose. It is appropriately short and wastes no words, earning a high score for conciseness.

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

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

Given the tool's complexity (4 parameters, 2 required, no output schema, no annotations), the description is insufficient. It does not explain the behavior when both after_section and before_section are provided, the return value (if any), or error states. A more complete description would cover these aspects.

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 add any additional meaning beyond what the schema provides (the parameters are already well-documented with 'gid' lookup instructions). No contribution is made by the description for 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 clearly states the verb (Move) and resource (an existing section) and specifies the scope (within its project). It distinguishes itself from sibling tools like section_create, section_update, and project_list_sections, though it could more explicitly contrast with those.

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 provide guidance on when to use this tool vs alternatives like section_update (which also changes section position) or explain prerequisites or limitations. There is no mention of what 'reorder' means in the context of the sibling tools.

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

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

No annotations are provided, so the description must disclose behavioral traits. 'Rename an existing section' indicates mutation but doesn't clarify idempotency, permissions needed, or what happens to existing data (e.g., children in section). It's minimally transparent but lacks depth about side effects or 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 with no wasted words. It's appropriately sized for a simple rename operation. Loses a point for being too terse—could briefly note prerequisites (e.g., section must exist) without harm.

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, no nested objects), the description covers the core purpose but omits behavioral details like whether the rename is instant, affects linked features, or requires special permissions. Completeness is adequate for a straightforward rename but could address potential agent questions about side effects.

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 50% (one of two parameters has description), and the description adds no parameter details. However, the schema itself covers section_gid and name adequately, with section_gid having a clear description including how to find it. The description could mention constraints (e.g., name uniqueness) but isn't required given schema quality. Baseline 3, increased to 4 because schema provides good guidance for both params.

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 'Rename an existing section' clearly identifies the verb (rename), resource (section), and action, which distinguishes it from siblings like section_create and section_reorder. However, it doesn't explicitly differentiate its purpose from the tool name itself, missing a slight opportunity to add scope or context.

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 renaming a section, but provides no guidance on when to use this tool versus alternatives (e.g., section_create for new sections, project_update for project-level changes). With no explicit when/when-not or alternatives, the agent must infer from sibling tool names.

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