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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is a mutating, potentially destructive operation. The description adds the requirement of an administrator token, which is useful behavioral context beyond the annotations. However, it doesn't disclose what happens on partial failure, whether items are validated, or whether the operation is idempotent. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is three sentences, each earning its place: the action, the scope, and the auth requirement. It is front-loaded with the verb and resource. The parenthetical example 'e.g. Team TeamMembers' is slightly redundant with the schema's collection examples but adds clarity. No wasted words, though it could be tightened by removing the parenthetical.

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 mutating admin tool with no output schema, the description covers the core purpose, scope, and auth requirement. However, it doesn't mention what the response looks like, whether the operation is reversible, or what happens if items already exist in the collection. The sibling list shows admin_collection_remove exists, so the agent can infer the inverse, but the description itself is not fully complete for a destructive operation.

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

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

Schema description coverage is 75%, and the description adds meaning beyond the schema: it explains that 'collection' refers to a collection of a configuration/administration entity and gives examples of resource types. The 'items' parameter already has a rich schema description with examples, and 'resource' and 'collection' are described in the schema as well. The description reinforces the admin context but doesn't add much beyond the schema; however, the 75% coverage means the schema does most of the work, so a 4 is justified for the added context about admin resources.

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 items to a collection') and the resource scope ('configuration/administration entity'), with concrete examples like 'Team TeamMembers'. It distinguishes itself from the sibling admin_collection_remove by the verb 'Add' vs 'remove', and from write_collection_add by the 'Administration resources only' qualifier. However, it doesn't explicitly name the sibling it is not, so it's clear but not maximally differentiated.

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

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

The description gives explicit context: it is for administration resources only (Project, Team, User, Process, etc.) and requires an administrator token. This tells the agent when to use it (admin operations) and implies when not to (non-admin collection adds, which would use write_collection_add). It doesn't explicitly state exclusions or alternatives, but the admin-resources-only qualifier provides strong usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds the requirement of an administrator token and the restriction to administration resources, which is useful. However, it doesn't disclose side effects like whether removal is permanent, cascading, or reversible, and it doesn't mention any rate limits 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 two sentences, front-loads the action, and includes a list of example resources. It is concise and structured, though the list of examples is somewhat long and could be trimmed without losing meaning.

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

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

For a destructive admin operation with no output schema, the description covers the essential context: what it does, on which resources, and the auth requirement. However, it lacks details on the semantics of 'childIds' (e.g., whether they are IDs of items in the collection), potential side effects, and how it differs from delete_collection_remove. Given the destructive annotation and 4 required parameters, more guidance would be helpful.

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%: the 'resource' and 'collection' parameters have descriptions, while 'id' and 'childIds' do not. The description adds context that the collection belongs to a configuration/administration entity, but it doesn't explain the relationship between 'id' and 'childIds' (e.g., that 'id' is the parent entity and 'childIds' are the items to remove). The schema already provides type and constraints, so the description adds moderate value.

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

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

The description clearly states the action ('Remove items from a collection') and the resource scope ('configuration/administration entity'), and lists example resources. It distinguishes itself from sibling tools like admin_collection_add and delete_collection_remove by specifying the admin/configuration context, though it doesn't explicitly name a sibling.

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

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

The description provides clear context: it is for administration resources only and requires an administrator token. It implies when to use this tool (admin collection removal) versus alternatives like delete_collection_remove or write_collection_add, but it doesn't explicitly state when not to use it or name alternative 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?

Annotations already signal non-read-only, open-world, and destructive behavior; the description adds the critical auth requirement (administrator token) and the admin-only scope. It does not detail side effects beyond creation, but with annotations covering the risk profile this is sufficient.

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

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

Three short sentences with the core action first, followed by scope restriction and auth requirement. No filler or repetition of schema 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?

For a two-parameter create operation with good schema descriptions, this is adequate for invocation. It leaves gaps around return value, error/conflict behavior, and overwrite semantics, and there is no output schema to fill those gaps.

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

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

Schema coverage is 100% and both resource and fields have meaningful descriptions, including an example for fields. The tool description adds no parameter-specific meaning, so the schema carries the load; 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?

States a specific action ('Create') and a specific resource category ('configuration/administration entity'), then narrows to 'Administration resources only' with an explicit list. This distinguishes it from siblings like write_create and admin_update without opening schemas.

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 restricts use to administration resources and requires an administrator token, giving the agent concrete selection criteria. It does not explicitly name a non-admin alternative such as write_create, so it stops short of full when-not guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' adds no new safety signal beyond what is structured. The description does add useful context by requiring an administrator token and restricting the resource scope. However, it does not disclose whether deletion is hard or soft, whether it cascades, or whether it can be undone, which is especially relevant given the sibling tool admin_undelete.

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

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

Two compact sentences carry the full message: the first states the operation and resource scope, the second states the authorization requirement. There is no filler and the key scoping information is front-loaded.

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

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

The definition covers the essential invocation context: resource class, examples, and administrator-token requirement, and the schema provides the resource parameter naming guidance. However, it omits id semantics and any note about deletion permanence or recoverability, which matter for a destructive admin operation. It is adequate for basic invocation but not fully complete.

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

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

The input schema documents only the 'resource' parameter with meaningful guidance ('Resource name (UserStory) or plural path (UserStories); see read_meta'), while 'id' has no description. The tool description adds no parameter-level meaning and does not compensate for the unannotated id parameter. With schema coverage at 50%, this leaves the id semantics to inference.

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 names a specific operation ('Delete') and a clear resource class ('configuration/administration entity'), then enumerates concrete examples such as Project, Team, User, Process, Workflow, EntityState, Role, and CustomField. It explicitly limits the tool to 'Administration resources only', which distinguishes it from related destructive tools like delete_entity and delete_card. The abstract phrase is fully resolved by the examples and scope statement.

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

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

The description gives clear usage context: it should be used only for administration resources and requires an administrator token. This implies when-not-to-use conditions, but it does not explicitly name alternative sibling tools such as delete_entity for non-admin resources or admin_undelete for recovery. The guidance is clear but stops short of an explicit when/when-not versus alternatives statement.

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

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

Annotations already mark this as mutable (readOnlyHint=false) and destructive (destructiveHint=true), so the bar is lower. The description adds value by disclosing an authentication requirement (administrator token) and listing entity types that cannot be restored, which are behavioral details not present in the annotations.

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

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

Two sentences, no filler. The first sentence leads with the action and required inputs; the second adds an essential limitation. 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 single-parameter admin tool with no output schema, the description provides purpose, prerequisites, and exclusions. It is missing expected return behavior, but the operation is straightforward and the schema + annotations already cover much of the call contract.

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

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

Schema description coverage is 0%, so the description carries the semantic burden. It explains that the items are identified by 'id and entity type' and gives valid entityType examples, which directly clarifies the sole parameter. It doesn't mention that multiple items can be passed, but the schema's array structure covers 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 clearly states the verb 'Restore' and the resource 'deleted entities', with the key parameters (id and entity type) and concrete examples (UserStory, Project, User). It is immediately distinguishable from siblings like admin_delete or admin_update because no other tool mentions restoration.

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

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

It provides strong contextual guidance: 'Administrator token required' sets a prerequisite, and 'Comments, milestones and programs cannot be undeleted' gives an explicit exclusion. It does not name alternative tools, but the use case is so specific that a when-not-to-use list is the main missing element.

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

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

Annotations already flag readOnlyHint=false, destructiveHint=true, and openWorldHint=true, covering the write and potentially destructive nature. The description adds the admin token requirement, which is useful, but doesn't disclose additional behavioral traits like partial update semantics, side effects on related entities, or validation rules. It is consistent with annotations 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 concise sentences that front-load the verb and resource type, followed by a helpful list of examples and the auth requirement. No filler or repetition; every sentence earns its place.

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

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

Given the tool has 3 parameters including a nested object and no output schema, the description covers the core purpose and scope but omits behavioral details like partial vs. full replacement, error handling, or return values. It is adequate for a basic call but could be more complete for an admin-level mutation.

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

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

Schema description coverage is 67% (resource and fields have descriptions, id has none). The tool description adds no parameter details beyond what the schema already provides. The example in the fields schema is helpful, but the description doesn't clarify any parameter behavior or edge cases, so it does not compensate for the moderate coverage gap.

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

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

The description clearly states the verb 'Update' and the resource type 'configuration/administration entity', and lists specific examples (Project, Team, User, etc.). This distinguishes it from generic update tools like write_update by scoping to admin resources only. The purpose is unambiguous.

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

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

The phrase 'Administration resources only' provides a clear scope and implies it should be used for admin entities rather than regular ones. The requirement for an administrator token is a concrete prerequisite. It doesn't explicitly name alternative tools, but the restriction is sufficient for an agent to select it appropriately.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is covered. The description adds useful context about the 500-entity limit and id-only operation, but does not disclose other behaviors like partial failure handling, irreversibility, or permission requirements. This is moderate extra value beyond the annotations.

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

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

The description is only two sentences with the core purpose front-loaded. The phrase 'layer 1' is unexplained jargon that slightly detracts from clarity, but no words are wasted.

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

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

For a simple two-parameter destructive tool with annotations already marking it destructive, the description covers the essential scope. However, it leaves open questions about response format, partial deletions, and what 'layer 1' means, which an agent might need for safe 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?

With 50% schema description coverage, the tool description compensates by explaining that 'ids' are the entity identifiers and that all IDs belong to a single resource. It reinforces the resource parameter's meaning and clarifies the operation is id-driven, adding value beyond the bare schema.

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

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

The description uses a specific verb ('Delete') and resource scope ('up to 500 entities of one resource by id'), clearly distinguishing it from single-entity delete siblings like delete_entity. The 'by id' and 'one resource' constraints make the tool's purpose unambiguous.

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

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

The description implies bulk use through 'up to 500 entities' and 'bulk delete', but it does not explicitly name alternatives or state when to use this tool versus delete_entity or delete_card. It provides a constraint ('by id only') but leaves the selection logic to the agent.

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

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

Beyond the destructiveHint annotation, the description discloses meaningful behavior: type resolution, child-card deletion semantics, and the returned report of deleted items plus before/after parent state and efforts. This is critical for a destructive operation and goes well beyond what annotations alone convey.

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

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

The description is two sentences, front-loads the core action, and packs necessary nuance without fluff. Every sentence adds operational value.

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

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

Given the simple two-parameter schema, existing annotations, and no output schema, the description is complete. It explains the destructive behavior, the condition for child cards, and what the response will report, leaving little ambiguity for an agent deciding to invoke it.

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 only 50%, so the description carries extra weight. It adds semantic context for withChildren (child-card deletion) and clarifies that id alone is sufficient because the type is resolved. It does not elaborate on id format, but the schema already covers that precisely.

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 identifies the operation as deleting a card, with the specific nuance that the card type is resolved automatically. This distinguishes it from sibling tools like delete_relation, delete_entity, and delete_bulk, which operate on other resource types or bulk scopes.

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

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

It gives clear context on when withChildren must be included, enumerating child-card scenarios and explaining the deletion rule. It does not explicitly name alternative tools for non-card deletions, but for its intended use it provides sufficient guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds useful context: it clarifies the operation is a removal/unlink (not a hard delete), scopes it to 'removable collection', and gives a concrete example. It doesn't detail side effects or reversibility, but the 'unlink' framing plus the destructive annotation is reasonably transparent.

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

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

Two sentences, no filler. The core action and example are front-loaded, and the alternative routing is in the second sentence. 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 destructive mutation with 4 required params and no output schema, the description gives the essential context: what it removes, from what, and by what key. It also routes away from a likely alternative. It doesn't mention return values or side effects, but the example and 'unlink' framing cover the main decision an agent needs to make.

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%: resource and collection have descriptions, while id and childIds do not. The description adds meaning for childIds ('by child id') and collection ('removable collection'), but it doesn't explain the id parameter (presumably the parent entity id) or the exact format of childIds beyond what the schema shows. The description partially compensates for the schema gap but not fully.

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

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

The description states a specific verb ('Remove items'), a specific resource ('removable collection of an entity'), and a specific key ('by child id (layer 1)'). It also gives a concrete example ('unlink test cases from a test plan') and distinguishes itself from a sibling ('To unassign a person prefer write_unassign'). This clearly differentiates it from the many sibling tools.

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

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

The description explicitly says when to use this tool (removing items from a removable collection by child id) and provides an exclusion/alternative ('To unassign a person prefer write_unassign'). This is direct guidance for an agent choosing between delete_collection_remove and write_unassign, which is the most likely confusion.

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

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

Annotations already establish destructiveHint=true, readOnlyHint=false, and openWorldHint=true.concat The description adds meaningful behavioral context beyond those annotations: it reads the entity before deleting and reports what was deleted, which signals a safer, more transparent destructive operation. There is no contradiction with the annotations.

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

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

A single sentence packs the action, scope, and critical behavioral nuance (read-first, report deletion) with no filler. The most important information is front-loaded. The only minor ambiguity is the unexplained 'layer 1,' but that does not add bloat.

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

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

For a simple two-parameter tool, the description covers what it deletes and that it reports results, and annotations cover destructiveness. However, it omits which resources 'support delete,' how to discover them, and how it differs from other delete tools. With no output schema, a bit more guidance about the reported result would improve 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?

Schema description coverage is only 50%; the resource parameter is documented in the schema, but id is not. The description says 'one entity' but adds no detail about id formats, validation, how resource names/paths are resolved, or the 'see read_meta' relationship. It does not meaningfully compensate for the schema's gaps.

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

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

The description clearly states a specific verb ('Delete') and resource scope ('any resource that supports delete'), and adds a distinctive behavioral detail: 'Reads it first and reports what was deleted.' It is not a tautology. However, it does not explicitly differentiate itself from sibling delete tools like delete_card, delete_bulk, or admin_delete beyond the generic 'any resource' phrasing.

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?

There is no guidance about when to use this generic delete_entity versus the more specialized delete_card, delete_relation, delete_bulk, or admin_delete siblings. The phrase 'any resource that supports delete' gives scope but no exclusions, prerequisites, or alternative-selection logic. An agent must infer the intended use from the tool name and sibling list.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds non-inferable behavioral details: the relation is deleted in either direction, and the relation type name is required to disambiguate when multiple relations exist.

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

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

Two concise sentences with the core action front-loaded and a conditional usage note immediately following. Every word 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?

Covers the main operation, parameter purpose, and an important edge case (multiple relations). It does not discuss error behavior or idempotency, but given the simple schema and rich annotations, 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?

With 0% schema description coverage, the description compensates by indicating that id and to refer to two cards and that relation is a type name used to pick among multiple relations. The numeric format of id/to is already covered by 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?

States the specific verb 'Delete' and the resource 'relation between two cards', clarifying the directional scope. This clearly distinguishes it from sibling deletion tools like delete_card or delete_entity.

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 practical guidance for the optional relation parameter (pass the type name if multiple relations exist), but does not explicitly state when to prefer this tool over alternatives such as delete_card or write_relate.

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

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

Annotations already indicate destructiveHint=true, so the destructive nature is covered. The description adds useful authorization context by stating only the owner or an administrator can delete, which is behavioral information beyond what annotations provide. It could additionally mention irreversibility or side effects, but the destructive hint plus permission note make this solid.

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

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

The description is a single, front-loaded sentence that states the action and the key permission constraint without unnecessary words. Every part contributes to understanding the tool's behavior, making it appropriately concise.

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

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

Given the tool is simple (two string parameters, no output schema) and annotations already flag it as destructive, the description is close to adequate. The main gap is that it doesn't explain the two parameters, and it offers no return-value or error expectations. It provides enough for a basic call but is not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must explain what 'group' and 'key' mean and how they relate to the storage entry. It does not do this. The phrase 'one storage entry' only weakly implies that key identifies the entry and group might be a container, but this is left to inference rather than explicitly documented.

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

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

The description states a specific verb and resource: 'Delete one storage entry', which clearly distinguishes it from sibling tools like read_storage, write_storage, delete_bulk, and delete_relation. The singular 'one' also differentiates it from bulk delete operations. The permission qualifier adds additional scope without confusing the core purpose.

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

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

The purpose itself implies usage: use this when you need to delete a single storage entry. However, the description provides no explicit guidance about when to prefer this over related alternatives like delete_entity, write_storage, or admin_delete, and no exclusions or prerequisites are mentioned beyond the owner/admin constraint.

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

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

Annotations already mark the operation as read-only and non-destructive, but the description adds an important behavioral caveat: downloading requires Basic or cookie auth, and using an access token yields an HTML error page instead of the file. This goes beyond the annotations by warning about an authentication edge case that could cause failed downloads or confusing errors.

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 and every clause earns its place: the first sentence defines the returned fields, the second adds a critical auth warning. It is front-loaded with the core purpose and does not waste words on obvious details.

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

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

Given there is no output schema, listing the fields returned (name, size, type, owner, date, URL) is valuable. The auth caveat is also included, which helps agents anticipate failures. It lacks an explicit statement that the single parameter is the card ID, but the phrase 'Attachments of a card' makes this reasonably inferable. Overall, the description is nearly complete for a simple read-only metadata 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 0% and the only parameter is a bare 'id'. The description partially compensates by saying the tool returns 'Attachments of a card', implying the id is the card ID, but it never explicitly states that the 'id' parameter refers to the card. No example or further clarification is provided, so the parameter semantics are only weakly inferred rather than clearly documented.

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 identifies the resource as 'Attachments of a card' and enumerates the returned fields (name, size, type, owner, date, URL), making it clear this is a read operation for attachment metadata. It does not explicitly use a verb like 'list' or 'retrieve', but the tool name and field list make the purpose unambiguous. It is distinguishable from siblings like read_comments and read_card, though it does not name a specific alternative.

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 this tool should be used when you need attachment metadata for a card, and it warns about auth requirements for downloading. However, it does not explicitly state when to use this over related tools such as read_storage or write_attachment, nor does it specify exclusions. The usage context is clear enough only by inference from the resource and field list.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing exactly what will be returned, including plain-text description and counts.

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 core action is front-loaded: "Read any card ... by id." The remainder is a dense, purposeful enumeration of returned fields. It is long but every phrase adds information about scope or output.

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 carries the burden of describing return values, and it does so thoroughly: type, state, project, parent chain, teams, assignments, efforts, release, custom fields, tags, counts, and description. Combined with annotations covering read-only behavior, this is complete for a simple fetch-by-id tool.

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

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

The sole parameter is id, and the schema fully constrains it with integer/string type, pattern, and range. The description merely says "by id" and adds no new meaning beyond the schema, but because the parameter is a conventional card identifier, this is adequate.

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

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

The description uses a specific verb and resource: "Read any card ... by id," and enumerates card types and the full set of returned fields. This clearly separates it from sibling tools like read_comments or read_relations, which target only specific aspects of a card.

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 tool's use case: when you need full card details by ID. However, it does not explicitly state when to prefer this tool over alternatives such as read_get, read_query, or read_comments, nor does it provide any exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'GET' is consistent. It adds one useful behavior beyond annotations: 'fully paged' (automatic pagination), but it doesn't explain return shape, truncation behavior (covered for limit in the schema), or rate limits. With annotations as baseline, it adds a bit but not rich 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 entire description is one sentence: the verb and target are front-loaded, examples are compact, and the reference to read_meta is a purposeful pointer. No filler or repeated schema 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?

For a 10-parameter tool, the schema covers most parameters and annotations cover the read-only/open-world safety profile. The description supplies the missing path pattern and pagination behavior, and points to read_meta for vocabulary. The main gaps are the unexplained 'layer 1' term and the absence of output-shape guidance, but these are not fatal given schema richness.

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 90%, so the schema handles most parameter documentation. The description adds value by showing how resource, id, and collection combine into a path, and by telling the agent to consult read_meta for valid collection names. This is modest but real meaning beyond the schema fields.

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

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

The description opens with 'GET an inner collection of an entity' and gives concrete path examples (UserStories/{id}/Tasks, Bugs/{id}/Comments), so the operation and resource are clear. It distinguishes itself from read_meta by pointing there for collection names, but it doesn't explicitly differentiate from other read_* siblings such as read_comments or read_get.

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: you use it when you need a nested collection of an entity, and it directs the agent to read_meta for valid collection names. It does not state when not to use it or name alternative tools for top-level reads/search, so guidance is implied rather than 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?

Annotations already mark the tool read-only and non-destructive, and the description adds useful behavioral details: ordering (oldest first), output format (plain text), included fields (author, reply parent), and the cap behavior (most recent comments are kept when truncated). This goes beyond the structured annotations without contradicting them.

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

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

Two short sentences deliver the core purpose and the edge-case truncation behavior without wasted words. The most relevant information is front-loaded.

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

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

There is no output schema, but the description explains what is returned (comments as plain text with author and reply parent), the ordering, and the truncation behavior. Combined with the schema's limit documentation and the read-only annotations, an agent has enough to invoke the tool correctly.

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

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

Schema coverage is only 50% because id has no description, but the phrase 'comments on a card' implies id refers to a card. For limit, the schema already documents default/maximum and the truncated flag, and the description adds the consequence that the most recent comments are retained when capped.

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 the resource ('comments on a card') and key characteristics (oldest first, plain text, author and reply parent). It lacks an explicit verb like 'reads', but the tool name and the phrase make the operation unambiguous. It is clearly distinct from siblings such as read_card or write_comment.

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

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

The description gives clear context for when to use it: whenever comments on a card are needed, with the card identified by id. It does not explicitly name alternatives or exclusions, but the use case is clear enough that an agent will not confuse it with other read 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?

Annotations (readOnlyHint, openWorldHint, destructiveHint) already cover the safety profile. The description adds value by disclosing what the tool returns (context contents) and the behavior of the no-argument mode (global context). This goes beyond the annotations and gives the agent an accurate picture of the operation without contradicting any annotation.

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

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

The description is a single dense sentence that front-loads the core purpose and enumerates the return contents in a compact list. Every clause contributes meaning—parameter scoping, examples, and global fallback—with no filler or redundancy. It is appropriately sized for the complexity.

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 return contents and the no-argument behavior, which is sufficient for basic invocation. However, it leaves the 'acid' parameter completely undocumented, provides no output schema, and doesn't address how multiple parameter groups interact (e.g., ids vs. teamIds). For a read-only tool with optional params these gaps are notable but not fatal.

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

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

Schema description coverage is only 25% (only 'ids' is described). The description partially compensates by mapping 'entity ids' to ids, and 'projects and teams' to projectIds/teamIds, which clarifies those three parameters. However, the 'acid' parameter is entirely unexplained in both the schema and description, leaving a significant semantic gap for a low-coverage definition.

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 reads 'Targetprocess Context' and enumerates its contents: processes, practices, terms, custom field definitions, selected projects/teams, logged user, version. It also specifies the scope based on arguments (entity ids vs. projects/teams vs. global). While it doesn't explicitly contrast with sibling read tools, the name and content make 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 implies usage: pass ids, teamIds, projectIds, or nothing for global context. However, it provides no explicit guidance on when to choose this over siblings like read_meta, read_get, or read_query, and no exclusions. The 'Without arguments' clause gives a hint of a fallback mode, but the when-to-use guidance is largely left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context about the output shape (current id and source ids), but does not say what happens when a card has no conversions or whether the input id can be either a current or original id.

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, and the key resource and example are front-loaded. The phrasing is slightly awkward, but every part earns its place in explaining what the tool returns.

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 one-parameter read tool with strong annotations, the description covers the main output semantics and gives a clarifying example. However, it leaves ambiguity around the direction of lookup and omits behavior for non-converted cards, which matters given there is 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 0%, so the description must compensate. It does clarify that the operation concerns 'a card,' implying the id parameter is a card id, but it does not explicitly state the allowed id formats or whether the id should be the current or original form after conversion. Partial compensation for a single simple parameter.

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 identifies the resource as 'type conversions of a card' with a concrete example (bug converted to a user story), and specifies what the tool returns: the current id and the originating ids. The verb 'read' is only in the tool name, not the description, but the output semantics make the purpose clear.

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 this tool is for looking up conversion history for a card, but provides no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as read_history or read_relations. An agent would have to infer the intended scenario from the resource name and example.

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

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

Annotations already cover the read-only safety profile, and the description adds useful behavioral detail: returned fields include their type, dropdowns include allowed values, and passing field filters to a single field. It does not disclose pagination, limits, or the open-world caveat that allowed values may not be exhaustive, but it goes beyond the annotations.

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

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

Two short sentences convey the resource, output contents, and the key filtering behavior without filler. An explicit verb like 'Lists' would strengthen it, but it is compact and front-loaded.

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

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

For a read-only metadata lookup, the description provides the core purpose, an optional field filter, and output content, while annotations supply the safety context. However, with no output schema and four undocumented optional parameters, there is still ambiguity about how id is used and exactly what is returned when no arguments are provided.

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 provides no parameter descriptions, so the description must compensate. It clarifies the field parameter and ties type/project to the scoping context, but the id parameter is left unexplained and no valid values or expected formats are given for type and field.

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 names the resource—custom fields for a card type or a project entity type—and specifies what is returned: field types and allowed dropdown values. It is clear, though phrased as a noun phrase rather than an explicit verb and does not explicitly contrast itself with sibling read 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 only guidance is 'Pass field to see one field,' which is parameter-level filtering rather than tool-selection guidance. The description never states when to use this tool instead of other read_* tools, when it should precede write_set_custom_fields, or what exclusions or prerequisites apply.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results include the delete date and that restoration requires admin_undelete and an administrator token. It does not mention pagination or truncation, though the limit parameter's schema covers some of that.

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 one compact sentence, front-loading the resource type and adding only the relevant restore note. There is no filler or repetition of schema details.

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

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

For a simple two-parameter read tool, the description plus schema covers what is returned, how to select kind, and truncation behavior. It could be slightly more explicit about pagination or read authentication, but the readOnly annotation and the clear sibling context make this a minor 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 required 'kind' parameter is reinforced by the description's 'projects or users' and is already self-documenting via its enum. The 'limit' parameter is fully described in the schema, including default, maximum, and truncated behavior. With 50% schema coverage, the description provides enough added orientation.

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 that this tool returns deleted projects or users, with their delete date, which is a specific verb plus resource. It clearly distinguishes itself from read_projects/read_people by the 'deleted' qualifier.

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 resource scope is explicit: use this when you need deleted projects or users. It also routes restoration to admin_undelete with an administrator token. It does not explicitly say 'do not use for active entities,' but the 'deleted' qualifier makes the boundary clear.

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

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

Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description's extra value is the concrete constraint that inner collections in include return at most 1000 items — genuinely useful behavioral context an agent couldn't infer from annotations. The 'layer 1' hint also suggests a scoped access layer. No contradiction with annotations.

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

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

Three sentences, zero filler. The core purpose is front-loaded, followed by a single behavioral constraint and a sibling-routing rule. Every sentence earns its place.

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

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

Complete enough for a read-by-id tool: purpose, an important pagination limit, and a routing rule are present, with annotations covering safety and schema covering parameters. Minor gaps remain — 'layer 1' is never explained, and error/not-found behavior is unspecified — but these are low-stakes for a safe read operation 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 80%, so the schema already documents append, exclude, include, and resource with examples. The description adds marginal value by clarifying include behavior (inner-collection limit) and confirming id-based retrieval, but the schema carries most of the parameter burden.

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

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

States a specific verb (GET), resource scope (one entity of any resource), and access method (by id), making it instantly distinguishable from sibling tools like read_collection (plural) and read_query (search). The 'layer 1' qualifier adds scope nuance, and naming read_card as the preferred tool for cards further disambiguates.

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 an explicit exclusion with a named alternative: 'Prefer read_card for cards.' The purpose statement itself implies the primary use case (fetch one entity by id). It doesn't enumerate alternatives for other scenarios (e.g., when to choose read_query over this), but the guidance it gives is concrete and actionable.

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

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

Beyond the read-only/non-destructive annotations, the description discloses ordering (oldest first), cap semantics (most recent retained), default scope (state/effort/release/iteration), and full-mode behavior (changed fields and new values). This is substantial behavioral context for a tool with no output schema.

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

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

Three sentences with no filler; the first sentence gives the core behavior, the second distinguishes output modes, and the third handles parameter nuance. Every clause contributes.

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 the absence of an output schema, the description orients the agent on return content and shape: history list, oldest first, default vs full fields, and truncation behavior. Combined with the schema's limit/resource details and read-only annotations, an agent has what it needs 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?

With only 50% schema description coverage, the description compensates by explaining full semantics, the resource/id resolution rule (cards vs other entities like Comment), and the distinction between default simple and full history. Limit's semantics are already covered in the schema, so no gap remains.

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?

Opens with the exact deliverable ('Change history of an entity') and adds ordering, cap-retention behavior, and simple vs full mode, making it unmistakable among the many read_* siblings. The phrase 'full: true returns every change' also makes the retrieval action explicit.

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 use case is clear: any agent needing entity change history, with an explicit choice between lightweight history and full field-level history. It does not name sibling alternatives or state exclusions, but the purpose is unique enough that an agent can select it without ambiguity.

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

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

Annotations already mark this as read-only and non-destructive. The description adds behavioral context beyond the annotations: sorting order (newest first), the meaning of currentOnly, and the scope behavior when team/project are absent. This is useful and consistent with the annotations.

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

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

The description is two compact sentences with no filler. The most important scoping distinction is front-loaded, and the fallback behavior is stated efficiently. Every sentence adds semantic 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 read-only tool with four optional parameters, this description covers the key invocation scenarios and ordering semantics. It does not describe the return value shape, but there is no output schema and the schema's limit description already covers truncation. The only minor gap is behavior when both team and project are supplied, which is left ambiguous.

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

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

Schema description coverage is only 25%, so the description carries most of the parameter meaning. It clarifies team, project, and currentOnly semantics and the interaction between them. The limit parameter is not mentioned in the description, but the schema itself documents its default, max, and truncated behavior, so the gap is minor.

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 names a specific resource (team/project iterations/sprints), explains the core variants (team, project, or all teams without a selector), and orders results newest first. This clearly distinguishes the tool from siblings like read_releases or read_projects without needing to inspect the schema.

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

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

The description gives clear context: pass a team for team iterations, a project for project iterations, and currentOnly to get running iterations. It also states the fallback behavior when neither team nor project is given. It does not explicitly name alternatives or exclusions, but the usage conditions are clear enough.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful conditional behavior: without a resource it lists every resource with operations; with a resource it details fields, references, and collections. This parameter-dependent behavior is not inferable from annotations and gives the agent a clear expectation of output scope.

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

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

Four short sentences, each earning its place: purpose, behavior without resource, behavior with resource, and usage guidance. The conditional behavior is front-loaded after the core purpose, and there is no repetition of schema content. It is compact yet information-dense.

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 one optional parameter, no output schema, and annotations covering read-only safety, the description fully covers what an agent needs: when to call it, what to pass, and how the output varies. No critical information about expected return shape, permissions, or side effects is missing – safety is in annotations, behavior is in description.

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

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

Schema coverage is 100% and the parameter description already explains the singular/plural format. The description goes further by explaining the semantic effect: omitting the parameter returns the full catalog, while providing it scopes to that resource's fields and relationships. This adds value beyond the schema by linking the parameter to output behavior.

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

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

The description starts with a specific verb-resource pair: 'Describe the Targetprocess resource catalog read from this instance.' It then clarifies the two modes (with/without a resource), which distinguishes it from data-returning siblings like read_query and read_card. The phrase 'Use it before read_query/write_create' further anchors its unique meta-purpose.

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

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

The instruction 'Use it before read_query/write_create' explicitly tells the agent when to call this tool relative to the most relevant alternatives. It implies the recommended workflow without needing to search sibling schemas. This is direct, actionable guidance.

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

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

Annotations already indicate a safe read operation. The description adds useful behavior beyond annotations: the default open-state filter, the grouping of results by state, and the scoping to the token owner's assignments.

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 dense sentence with no filler. It front-loads the core subject, then adds the default behavior and output characteristic efficiently.

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

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

For a read-only tool whose annotations cover safety and whose schema covers type and limit, the description is nearly complete. The remaining gaps are the exact semantics of state/includeClosed and the response shape beyond counts per state.

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 documents type and limit, but state and includeClosed have no descriptions. The phrase 'open ones by default' partially clarifies includeClosed semantics and 'counts per state' relates to the state parameter, but the description does not fully compensate for the undocumented 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 says the tool returns cards assigned to the current token owner, with open cards as the default and counts per state. This distinguishes it from generic sibling tools like read_card or read_search, though it lacks an explicit action verb like 'list' or 'read'.

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 tool should be used when you need the current user's assigned cards, especially open ones grouped by state. However, it does not explicitly state when not to use it or mention alternatives such as read_card or read_search.

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

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

The description adds behavioral detail beyond the readOnly/openWorld annotations: it discloses that results are 'fully paged over all users' and that matching requires every word to match. This helps the agent anticipate potentially large result sets and exact-match behavior. No contradiction with annotations.

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

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

Three short sentences deliver distinct, high-value information: search behavior, default listing, and a practical tip. There is no filler or repetition, and the core purpose is front-loaded.

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

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

For a simple lookup tool with no output schema, the description covers the essential behavior and query semantics, but it doesn't document 'includeInactive' and doesn't describe the return payload beyond the presence of ids. The missing parameter explanation is a gap, though the parameter name is fairly self-explanatory.

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

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

Schema description coverage is only 33% (only limit is described). The tool description compensates somewhat by explaining that 'query' matches name, login, or email and that all words must match, plus the no-query default. However, it leaves 'includeInactive' undefined, so one parameter remains semantically underspecified.

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 the exact resource ('people'), the search criteria (name, login, email), and the key matching constraint ('every word must match'). This clearly differentiates it from broader search siblings like read_search or read_query, even without naming them.

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 context such as the no-query default ('Without a query, lists everyone active') and a practical follow-up ('Use the returned ids when a name is ambiguous'), but it does not explicitly state when to choose this tool over alternatives like read_search. Usage is implied but no alternatives or exclusions are mentioned.

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

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

Annotations already cover read-only and non-destructive behavior, lowering the burden. The description adds useful behavioral context beyond the schema by stating the active-by-default filter and mentioning the returned fields ('abbreviation and process'), which helps the agent predict output shape.

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

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

The description is a single sentence that front-loads the core action, then adds the most important qualifiers and output hints. Every piece earns its place, with no filler or repetition of the tool name.

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

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

For a simple list tool with two optional parameters and no output schema, the description is largely complete: it covers the entity, default filtering, output fields, and the one filter option. It stops short of perfect completeness by not addressing pagination, ordering, or exact query matching, but those are minor for this scope.

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

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

With schema description coverage at 0%, the description must compensate, and it does: 'optionally filtered by name' explains the query parameter, while 'active by default' implies the role of includeInactive. It does not spell out exact matching semantics or the precise effect of includeInactive=true, but it gives enough for correct use.

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

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

The description states a specific action and resource: 'List projects', with clear qualifiers about active-by-default, output fields, and optional name filtering. This distinguishes it from sibling read_* tools that target other entities like comments, relations, or card data.

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 context: call it to list projects, know that inactive projects are excluded by default, and use the query parameter to filter by name. It does not explicitly name alternatives among the many read_* siblings, so it falls short of the top score.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond those annotations: it is fully paged, has a default limit of 500 and max of 5000, and returns {count, truncated, items}, which helps an agent anticipate truncated results. No contradiction with annotations is present.

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

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

Two sentences are efficient and front-load the core purpose before pagination and return shape. The unexplained 'layer 1' costs some clarity, and the default/max limit repeats the schema, but every sentence otherwise 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 an 8-parameter generic query tool, the description combined with a 100%-covered schema covers most call mechanics. It is incomplete as a routing aid because it does not clarify the relationship to read_collection or read_v2_query, does not explain 'layer 1', and has no output schema to detail the return values further.

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

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

Schema coverage is 100%, so the description does not need to redefine every parameter. It adds meaningful guidance by telling agents to 'use include to keep results small' and by emphasizing default/max limits and the truncated flag, which helps with selecting parameter values.

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 ('Query a collection of any resource') and names key capabilities (where/include/orderBy, paging), so an agent can tell what the tool does. It stops short of 5 because the cryptic 'layer 1' and lack of explicit differentiation from siblings like read_collection or read_v2_query leave room for 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 establishes a clear context—generic collection queries with where/include/orderBy—and offers a practical tip to use include to keep results small. However, it never says when to prefer this tool over read_collection, read_v2_query, or read_search, and 'layer 1' is not explained as an alternative or exclusion.

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

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

Annotations already cover the read-only and non-destructive nature, as well as the open-world hint. The description adds useful context about bidirectional relations and included related cards, but does not disclose pagination, limits, or response structure details.

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

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

The description is a single, efficient sentence that front-loads the core purpose and enumerates the relation types without any 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?

Given this is a simple one-parameter read operation, the description is largely complete. Annotations provide the safety and open-world context, and the relation types plus related-card inclusion are enough for an agent to select and invoke the tool correctly.

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

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

With schema description coverage at 0%, the description must provide meaning for the id parameter. 'Relations of a card' implies id is the card identifier, which is the essential meaning, though it is implicit rather than explicit.

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 identifies the tool's purpose as returning relations of a card in both directions, listing specific relation types and noting that the related card is included. It does not explicitly differentiate from sibling read tools, but the resource and scope are 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?

No usage guidance is provided. The description does not say when to use read_relations versus write_relate or delete_relation, nor does it mention any alternative tools for related operations.

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

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

The annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by explaining ordering (newest first) and the meaning of the currentOnly filter. It does not describe the full return shape, but that burden is partially covered by the limit parameter's note about truncation.

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

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

The description is a single compact sentence with no filler words. It front-loads the core behavior ('Releases, newest first') before the optional filters. Every clause earns its place.

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

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

For a simple read tool with 3 optional parameters, no output schema, and read-only annotations, the description plus schema cover the essential semantics: what is returned, the ordering, the filters, and the truncation behavior. It is not missing critical information, though it doesn't spell out default values for currentOnly or project type handling in 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 only 33% (only 'limit' is documented in the schema), so the description must compensate. It does: 'optionally for one project' explains the project parameter, and 'currentOnly for releases in progress' explains the boolean. The limit parameter is already well-described in the schema. The explanation is concise but adequate.

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 identifies the resource ('Releases') and specifies sorting behavior ('newest first') plus two optional filtering dimensions (project, currentOnly). It distinguishes itself from sibling read_* tools by name and scope, though it uses a noun phrase rather than an explicit verb like 'read' or 'list'.

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 useful context for filters—'optionally for one project' and 'currentOnly for releases in progress'—but never states when to prefer this tool over alternatives or when not to use it. Usage is implied by the tool name and the read_* sibling grouping, but no explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered without the description's help. The description adds the hasEffort field semantics, which is useful since there is no output schema, but it discloses no traits like ordering, pagination, or whether custom roles are included (the '...' only loosely aligns with openWorldHint). No contradiction with annotations.

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

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

Two short sentences front-loaded with the action and resource, followed by a targeted clarification of a non-obvious field. The role examples and hasEffort explanation each earn their place; there is zero 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?

For a 0-param, read-only list tool, the essential facts are present: what is returned and what the key field means. The hasEffort explanation partially compensates for the absent output schema, though other role attributes are left unspecified. The description is adequately complete for the tool's simplicity.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description carries no parameter burden — this matches the baseline of 4 for 0-param tools. The hasEffort explanation aids output comprehension rather than parameter semantics, which is a reasonable bonus given the missing output 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 gives a specific verb+resource ('List roles') and concrete examples ('Developer, Product Owner, ...') that make the domain recognizable. Introducing the hasEffort field clarifies what the result set is about even before calling. It doesn't explicitly differentiate from sibling tools, but the resource 'roles' is unique among the read_* siblings, so confusion risk is low.

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 hasEffort explanation implies a usage scenario — determining which roles can carry effort — which is indirect usage context. However, there is no explicit when-to-use, when-not-to-use, or routing to related siblings such as read_people or write_set_role_effort. The agent must infer the appropriate call context.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint: false), the description adds valuable behavioral details: the #id and bare-digit matching semantics, the 'me' shortcut for assignee, the open-cards-only default unless includeClosed, the 'never guessed' resolution of ambiguous names, and the newest-modified-first ordering. This goes well beyond what annotations convey.

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

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

The description is two dense sentences with no filler. The primary search criteria are front-loaded, followed by key behavioral constraints and ordering. Every clause contributes useful information.

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

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

For a search tool with 8 optional parameters, no output schema, and no required parameters, the description covers the important operational details: field semantics, filtering defaults, ambiguity handling, and sort order. It does not describe pagination beyond the schema's limit field, but the description is otherwise sufficient for an agent to invoke the tool correctly.

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

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

With 75% schema coverage, the schema already documents most parameters. The description adds meaningful semantic nuance: bare digits match both id and name, 'me' is a self-reference for assignee, and includeClosed controls the open-only default. It does not fully detail all parameters, but it materially enhances understanding beyond the schema.

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

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

The description clearly identifies the action ('Find cards') and the resource (cards), and enumerates the searchable fields: text/name/#id, type, state, project, assignee, and tag. This is specific enough to differentiate from tools like read_card, though it does not explicitly name sibling alternatives or exclusion criteria.

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

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

Usage context is implied through the search criteria and the statement 'Open cards only unless includeClosed.' The description also clarifies resolution behavior for names/states. However, there is no explicit guidance on when to prefer this tool over siblings like read_query or read_card, nor any when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral detail: team sub-workflow states are flagged isTeamWorkflow, and for a card, both its current state and team states are included. No annotation contradiction exists.

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

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

Two sentences, no fluff. The main purpose is front-loaded, and the second sentence adds useful behavioral nuance without repeating schema or annotation information.

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

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

For a read-only tool with full schema coverage, the description is nearly complete: it defines scope, mentions team-state inclusion, and signals the isTeamWorkflow flag. It does not clarify the behavior when no parameters are provided, but that is a minor gap given the clear card-vs-entity-type 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between the card id and its own project's process, and between entity type and project, clarifying when type/project parameters are relevant.

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 identifies the resource ('states') and the two contexts it applies to: a card or an entity type in a project. It is specific and scoped, but it does not explicitly distinguish this tool from sibling read tools such as read_card or read_meta.

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 two valid usage contexts: states for a card or states for an entity type in a project. It gives clear context but does not mention alternatives, exclusions, or when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, which cover the basic read-only/open-world profile. The description adds value by explaining the storage hierarchy, the publicData/userData split, and the select/where syntax, giving behavior beyond what annotations communicate.

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

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

The description is compact and well-structured, front-loading the domain context before the three argument modes. It avoids filler but is somewhat dense with storage-specific jargon such as 'select/where in storage syntax'.

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 must explain return shapes; it does explain what each mode returns, but it omits details like pagination, error cases, or the exact fields available in a group object. The select/where example helps but is not a complete grammar.

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 only 20% (only limit has a description), so the description carries most of the semantic weight. It clarifies key and group semantics and provides a concrete select/where example, though a fuller syntax specification for where/select would improve it further.

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

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

The description states a specific resource (storage with views, boards, settings) and clearly enumerates what the tool returns for each argument combination: groups, storages, or a single storage. It does not explicitly contrast with sibling read tools, but the storage focus is distinct enough to avoid 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 gives clear usage patterns via the 'No group / Group / Group + key' conditions, which effectively tells the agent how to shape a call. It does not mention when NOT to use this tool or name alternatives, but the provided branching guidance is concrete and actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds the active-by-default scoping behavior and the optional name filter, which is useful context. It does not cover pagination, return format, or sorting, but the annotation safety profile lowers the burden.

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

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

The description is a single front-loaded sentence with no filler. It states the core action, the default behavior, and the optional filter in the most economical way possible.

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

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

For a simple read-only list tool with two optional parameters and annotations covering safety, the description is largely adequate. Gaps remain around includeInactive semantics and the return shape, and since there is no output schema, those details are not covered elsewhere.

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 0%, so the description must compensate. It does convey that 'query' is a name filter and that active-by-default implies includeInactive defaults to false. However, it does not define query matching behavior (exact, substring, case sensitivity) or explicitly map includeInactive=true to including inactive teams.

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 'List' and the resource 'teams', and adds useful scope details: active by default and optional name filtering. It does not explicitly distinguish itself from sibling read tools, but the resource is unambiguous and no other tool targets teams.

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

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

Usage is implied: use this tool to list teams. However, it provides no when-to-use guidance versus sibling tools like read_meta or read_context, and it does not explicitly explain when includeInactive should be set to true. There are no exclusions or alternative routing.

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

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

Annotations already establish this as safe and non-destructive (readOnlyHint=true, destructiveHint=false). The description adds useful context about the response contents, such as run-ordered steps and recent runs, but it does not disclose recursion depth for child plans, pagination, or other edge behaviors. This is adequate given the annotations, 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?

The description is a single compact sentence with no filler. Every phrase adds information about what is included in the result, and the resource type is front-loaded.

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

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

For a read-only tool with only two simple parameters, the description gives a reasonable picture of the return payload despite the lack of an output schema. It covers the main elements an agent would need to decide whether to call this tool, though details like child-plan recursion and response limits are left unspecified.

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 documents the 'runs' parameter ('How many recent runs to include (default 10)'), and the description only mirrors that concept with 'recent test plan runs.' The 'id' parameter has no schema description and the tool description does not compensate by explaining what it identifies. With 50% schema coverage and no compensating description detail, parameter meaning is only partially supported.

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 identifies the resource being returned—a test plan with its test cases, steps in run order, child test plans, and recent runs. It is distinct from generic siblings like read_query or read_get, though it lacks an explicit verb like 'reads/retrieves' and relies on the tool name to convey the action.

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

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

No explicit when-to-use guidance is provided, and no alternative tools are mentioned. The description implies this is the tool for fetching test-plan details, but it never states when to choose it over a sibling like read_history or write_test_run, nor does it mention exclusions 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 annotations already establishing read-only and non-destructive behavior, the description adds useful behavioral context beyond them: it reads two different entity types (Time and TimeRecord), includes task records within a story, and returns both kinds when queried by person alone. No contradiction with annotations.

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

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

The description is concise and front-loaded: the first sentence states purpose and scope, the second states the return value, and the remaining sentences add necessary nuance. The phrasing is somewhat dense but every sentence earns its place.

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

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

There is no output schema, so the description responsibly explains return content and the two entry types. But with zero required parameters, it never states what an empty call returns or whether id and user act as filters or alternatives, leaving a meaningful gap for an agent deciding how to invoke it.

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 documents id, user, and limit. The description compensates for the undocumented from/to by giving the YYYY-MM-DD format and optionality. However, it does not clarify what happens when both id and user are provided, or when no parameters are supplied, so its contribution is only partial.

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: 'Time logged on a card, or by a person,' and explicitly states the return value ('entries and the total spent'). This is precise enough to distinguish read_times from the sibling read_* tools. The later Time/TimeRecord clarification adds detail without obscuring the core purpose.

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

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

The description conveys the input modes clearly: card, person (or 'me'), and optional date range. However, it never names an alternative tool or explains when not to use this one, so the usage guidance is implied rather than 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: v2 omits null fields (absence means null), the entity must be singular, and aggregations are done via the result parameter. This supplements the annotation-based safety profile with concrete query 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 dense but compact, with four sentences that each earn their place. The inline example compresses a lot of syntax guidance. It is not overly verbose, though it could be slightly more scannable; still, it is efficient for the complexity.

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 core query capabilities (where, select, result, filter), the null-field behavior, and entity singular constraint. It does not explain error handling or detailed return formats beyond the truncated flag mentioned in the limit schema description, but for a read-only query tool it is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is only 38%, so the description must compensate for the many undocumented parameters. It does so for the most complex ones: where, select, result, and filter each get syntax explanation and/or an example. It does not cover limit, orderBy, or includeDeleted, but limit and orderBy have schema descriptions, and includeDeleted is minor. Overall, it adds significant meaning beyond the bare 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 'Targetprocess REST v2 query (read-only)', which names the specific API version and action, and immediately clarifies it is read-only. It distinguishes itself from the sibling read_query (presumably v1) by explicitly calling out 'v2' and noting the singular entity form, so an agent can tell them apart without opening schemas.

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

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

The description gives clear context: this is for v2 queries with a specific syntax, and provides examples. However, it does not explicitly name alternatives (e.g., read_query for v1) or state when not to use this tool, so an agent must infer the boundary from the v2 labeling and syntax examples.

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

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

Even though destructiveHint is already true, the description adds precise behavioral detail: it 'adds to existing assignments', only removes others when 'exclusive: true' is explicitly passed, and it reports removed assignments plus reads assignments back. This is exactly the kind of safety-relevant nuance an agent needs before invoking a destructive write.

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 pack the core purpose, supported value forms, default behavior, exclusive exception, and return behavior with no filler. The key 'adds to existing assignments' clarification is front-loaded.

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

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

With no output schema and only sparse parameter descriptions, the description compensates well by stating the write effect, exclusivity behavior, and what is reported. It falls just short of full completeness because the required `id` parameter is never explicitly defined as the card identifier.

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 clarifies the semantics of user, role, and exclusive beyond the schema examples, but it never explains what the required `id` parameter refers to (presumably the card id). Since schema_description_coverage is only 50% and `id` has no schema description, this is a real gap.

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

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

The description opens with a specific verb and resource: 'Assign a person to a card in a role', which clearly distinguishes it from read operations and from write_unassign. It also specifies accepted user forms ('names or ids; "me"') and the additive/exclusive behavior, so an agent understands the tool's operation at a glance.

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

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

It gives clear context for when to use the tool (assigning people to roles on a card) and explains the default additive behavior versus exclusive mode. It does not explicitly name write_unassign as the sibling for removing assignments, so some routing guidance is left implicit.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, which the description does not contradict. It adds genuinely useful behavior beyond annotations: pounce never reads local files itself (so the client decides what may be uploaded) and attachments are read back to confirm arrival. It doesn't clarify what the destructive aspect means (e.g., overwriting existing attachments), but the annotations already carry that flag.

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, purpose front-loaded in the first. The endpoint reference, the client-side content disclosure, and the read-back confirmation each add distinct value. The middle sentence is slightly wordy but packed with meaning; nothing is wasted.

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 two-parameter upload tool, the description covers the essential call semantics and even hints at success verification via read-back. But there is no output schema, and the description doesn't specify what a successful call returns, how failures surface, or whether uploading replaces existing attachments — which matters given destructiveHint=true.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the core semantic of the files parameter (base64 content plus a name), which aligns with contentBase64 and name in the schema. However, it never explicitly states that id is the card identifier, and mimeType is left entirely undocumented, so compensation is only partial.

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 'Upload files to a card', a specific verb plus resource, and anchors it to the concrete endpoint (UploadFile.ashx). This clearly separates it from read_attachments (reading) and from other write_* siblings that create or update cards rather than attaching files.

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 usage context is inferable from the action (attaching files to a card), and the read-back note hints at the verification workflow, but no explicit alternatives, exclusions, or when-to-use conditions are stated. An agent must guess that read_attachments is the counterpart for retrieval.

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

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

The description adds real behavioral context beyond the annotations: Id-based upsert semantics and the all-or-nothing validation guarantee ('nothing is sent if any item is invalid'). The annotations already signal destructive and non-read-only behavior, and the description does not contradict them, though it doesn't disclose post-validation partial-failure behavior.

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

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

Two sentences, with the primary action and limit front-loaded in the first sentence and the key behavioral rule in the second. No filler, no repetition of schema-visible details.

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 resource choice, item semantics, batch limit, and initial validation, so an agent can invoke the tool. However, there is no output schema and no mention of what the call returns, and there is no detail on failure behavior after validation or an explanation of 'layer 1,' leaving gaps for a bulk mutation 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 coverage is only 50%: 'resource' is described, but 'items' has no attached description. The description compensates by explaining that items with 'Id' update and items without create, plus the 500-item cap and validation behavior. This adds meaningful semantics beyond the bare JSON 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 states a specific verb ('Create or update'), a bounded resource scope ('up to 500 entities of one resource'), and the one-call bulk nature. This is clear, though 'layer 1' is unexplained and the description does not name sibling tools to explicitly distinguish itself from single-entity write operations.

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

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

Bulk usage is implied by 'up to 500 entities of one resource in one call,' which suggests when this tool is appropriate, but there is no explicit guidance on when to prefer it over write_create, write_update, or other write siblings. No when-not-to-use conditions or alternatives are named.

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

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

Annotations already establish that this is a mutating/destructive operation. The description adds valuable behavior beyond that: it appends rather than replaces, which answers a common overwrite concern. It does not cover authorization, return value, or side effects, but the append guarantee is meaningful.

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 dense sentences, with the primary operation and append semantics front-loaded, followed by routing guidance. Every sentence earns its place and there is no filler or repetition.

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

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

For a mutation tool with no output schema, the description covers the operation's semantics, the fact that nothing is replaced, and key exclusions, while the schema references read_meta for valid resource and collection names. The phrase 'layer 1' is opaque and not explained, but overall an agent has enough context to call this correctly.

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

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

The schema already documents resource, collection, and items with examples, covering 75% of parameters. The description itself adds little per-parameter detail, and the id parameter remains undocumented. This is an acceptable baseline because the schema carries most of the burden.

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

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

States a specific action ('Add items') with a clear target ('an addable collection of an entity') and the key semantic detail that posts APPEND without replacing. It also distinguishes itself from siblings like write_assign, write_team, and write_set_role_effort by naming them directly.

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

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

Explicitly tells agents when not to use this tool: for assignments, teams, and role efforts, prefer write_assign, write_team, and write_set_role_effort. This is clear routing guidance that helps an agent choose the correct sibling without opening their schemas.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description does not contradict these. It adds useful behavioral detail about format handling (markdown vs plain text vs HTML) and replyTo semantics, which goes beyond the annotations. However, it does not elaborate on the destructive implications or open-world side effects suggested by openWorldHint=true, so the added context is moderate.

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

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

The description is three short sentences, front-loaded with the primary action. Every sentence earns its place: purpose, format behavior, and replyTo meaning. There is no filler or redundancy, making it efficient and easy to parse.

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

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

For a write tool with 5 parameters and no output schema, the description covers the core action and clarifies the two most ambiguous parameters (format and replyTo). It omits explicit explanation of 'id' (card identifier) and 'private', but these are relatively self-evident from the context. Given the annotations cover the read-only/destructive profile, the description is adequately complete for a simple comment operation, though not exhaustive.

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

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

Schema description coverage is only 20% (only 'format' has a description), so the description must compensate. It clarifies 'format' (markdown vs HTML vs text) and 'replyTo' (answers another comment), which is helpful. However, it does not explain 'id' (presumably the card id) or 'private', leaving the agent to infer from the name and context. The description partially fills the gap but not completely.

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 'Add a comment to a card', a clear verb+resource pair that unambiguously states the tool's function. It also distinguishes itself from the many sibling write_* tools by focusing specifically on comment operations, and the added format/replyTo details reinforce the purpose without ambiguity.

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

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

The description implies when to use the tool (to add a comment) but does not explicitly contrast it with alternatives or state when not to use it. It provides no guidance on choosing this over, say, write_create_card or write_update_card, leaving the agent to infer from the purpose alone. This is clear context but no exclusions.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true, so the description doesn't need to restate those. It adds valuable behavioral context: validation against the catalog before sending, the ability to include nested children, and the rule to never include Id. It doesn't describe failure modes or side effects beyond the annotation hints, but the added validation and nesting details justify a 4.

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

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

The description is compact and front-loaded: it states the core purpose first, then gives a concrete example, then the critical constraint (never include Id), then custom fields, and finally the sibling alternative. Every sentence earns its place and the structure guides the agent from general to specific.

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 generic create tool with two required parameters and no output schema, the description covers the essential usage: what to pass, how to format it, what to avoid, and when to use a different tool. It doesn't explain return values or error handling, but those are less critical given the annotations and the tool's generic nature. The nested-object example and custom field guidance make it sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaning by explaining the fields parameter format with a concrete example, clarifying that nested children are allowed, and specifying that Id must not be included. This goes beyond the schema's generic 'Entity fields as Targetprocess JSON' description.

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

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

The description clearly states the tool creates an entity of any resource that supports create, with a specific example and explicit exclusion of Id. It also distinguishes itself from write_create_card by noting the card-specific alternative. The verb 'create' and resource scope are 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 says to prefer write_create_card for cards because it applies team rules, giving a clear when-not-to-use directive. It also provides guidance on nested children, custom fields, and the Id exclusion, which helps an agent decide when to use this generic create tool.

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

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

Beyond annotations, the description discloses important behaviors: project inheritance chains, pre-posting failure if no project resolves, removal of Targetprocess default assignments followed by exact assignment, per-role effort writing, and before/after reporting of parent state and role efforts. It also explains how markdown, HTML, and plain text descriptions are handled, which annotations cannot convey.

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

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

The description is front-loaded with purpose and scope, and every clause carries useful information; there is no filler. However, the first sentence is a dense run-on, and the behavior could be easier to parse with light structuring, so it is excellent but not perfectly concise.

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

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

Given 16 parameters, nested objects, and no output schema, the description covers the critical creation semantics and behavioral edge cases. It does not specify the response shape beyond reporting parent state and role efforts, and it omits prerequisites, but the description is complete enough for correct invocation of the main card-creation flow.

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

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

With only 44% schema description coverage, the description compensates by explaining the meaningful semantics of parent/project inheritance, assignee behavior, role efforts, tags, and custom fields. It also adds behavior around the format parameter ('HTML is sent as-is, plain text lines become paragraphs'). It does not fully document every parameter, but it covers the highest-risk semantics.

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

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

The description opens with a specific verb and resource: 'Create any card type' followed by an enumeration of concrete types (UserStory, Task, Bug, Feature, Epic, TestPlan, Request). It also lists the settable attributes and the team-rule behavior, making it clearly distinct from sibling tools like write_update_card or read_card.

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

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

The description gives clear context for when to use the tool: to create any card type with the described team-rule enforcement. It does not explicitly name alternatives such as write_create, write_bulk, or write_update_card, nor does it state when not to use it, so it stops short of the strongest routing guidance.

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

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

Annotations already convey that this is a mutating and destructive write operation (readOnlyHint=false, destructiveHint=true). The description adds concrete behavioral detail by specifying that unfollow removes the follow relationship and that the action can target another person, but it does not discuss permissions, idempotency, or failure behavior.

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

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

The description is a single 18-word sentence that front-loads the core action and uses a parenthetical to handle the parameter variation. Every clause adds meaning, and there is no filler or repetition of schema fields.

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

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

For a simple three-parameter mutation tool with annotations covering the safety profile, the description is sufficient: it states the operation, the target, the user scope, and the unfollow branch. Minor omissions like the default behavior when user is omitted and permission requirements are not 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?

Despite only 33% schema description coverage, the description gives meaningful semantics for all three parameters: 'a card' identifies id, 'for yourself or another person' maps to user, and 'with unfollow: true, stop following' explains the boolean flag. This compensates for the sparse schema, though id is not explicitly named as a parameter.

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 names a specific verb ('Follow'/'stop following'), a resource ('a card'), and a target scope ('for yourself or another person'). It clearly communicates the tool's function and distinguishes it from sibling tools by the unique 'follow' operation, though it does not explicitly name an alternative tool.

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

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

There is no guidance about when to use this tool versus alternatives like write_assign or write_relate, and no exclusions or prerequisites are stated. The only conditional ('unfollow: true') is an internal branch of this tool, not a selection between tools.

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

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

The description discloses meaningful behavior beyond the annotations: it explains the two data-model cases, default role selection, default person and date, and the fact that Targetprocess names TimeRecord entries itself. With destructiveHint and openWorldHint already provided, this adds useful context without contradicting them.

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

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

The key action is front-loaded and every sentence contributes relevant detail. The conditional second half is dense and slightly run-on, but it contains no filler and is appropriately sized for the complexity of the tool.

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 mutating tool with no output schema, the description covers the primary call context, parameter defaults, and the two possible record-creation behaviors. It lacks explicit return behavior and units for `spent`, but the annotations fill the safety profile, making it sufficient for correct invocation in most 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?

The description adds important semantics for date format/default, person default, and role default logic, which are not fully present in the schema. However, required parameters like `id` and `spent` still rely on inference, and `description` is not explained, only partially compensating for the 43% 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?

Opens with a concrete action ('Log time spent on a card for a person') and clearly identifies the resource and default subject. It also distinguishes itself from the sibling read_* and write_* tools by focusing specifically on time logging rather than general card updates or reads.

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

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

The description gives clear context for when the tool applies and even branches based on whether the process tracks time or uses a TimeRecord type. It does not explicitly name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already establish that this is not read-only and can be destructive. The description adds valuable behavioral context beyond the annotations: the default relation type, the outbound vs inbound direction semantics, and especially the idempotent behavior that an existing identical relation is left alone.

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

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

Every sentence earns its place: the first states the action and relation types, the second defines direction semantics, and the third clarifies idempotence. The information is dense but compact, with no filler.

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

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

For a write operation with no output schema, the description covers the essential invocation details: required parameters, default values, accepted relation types, and direction behavior. It could additionally clarify what happens when a non-identical relation already exists, but given the annotations and sibling context, the description is reasonably complete.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It compensates thoroughly: it explains the 'relation' parameter's valid values, the default behavior for 'direction', and the semantic roles of 'id' and 'to' in both outbound and inbound cases. This is well beyond what the bare schema provides.

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

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

The description opens with a specific verb and resource ('Relate two cards') and enumerates the supported relation types, making it immediately clear what operation is performed. This distinguishes it from sibling tools like write_create_card and delete_relation, which clearly have different purposes.

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

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

The description explains how to use the tool (outbound/inbound direction, defaults, idempotence) but gives no explicit guidance on when to choose this tool over alternatives such as write_update_card or delete_relation. There are no stated prerequisites, exclusions, or when-not-to-use hints.

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

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

Beyond the annotations, it discloses that dropdown values are validated against field options before anything is sent, that null clears a field, and that values are read back after the operation. This materially informs the agent about preconditions, deletion semantics, and return 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?

Three short sentences deliver a purpose statement, an example, and key behavioral caveats with no filler. The first sentence front-loads the core action; the rest adds essential details without repetition.

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

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

The description covers the main semantic requirements for a 2-parameter tool: what fields means, how clearing works, validation, and that a readback occurs. It leaves the exact return shape unspecified and does not explicitly define the id parameter, but the references and annotation set make it reasonably complete for an agent.

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

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

With 0% schema description coverage, the description compensates well for the 'fields' object by giving a concrete name-value example and explaining null and dropdown handling. The 'id' parameter is only implied as the card identifier by the phrase 'on a card', not explicitly described in terms of type or format, so some burden remains.

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 opening phrase 'Set custom fields on a card by name' names a specific verb, resource, and mechanism, and the example mapping makes the intent unmistakable. This distinguishes it from sibling write tools like write_update_card, which handle ordinary card fields, and from read_custom_field_options.

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

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

The description gives clear context: the tool is for setting named custom fields on a card, and it explicitly points to read_custom_field_options for dropdown options, implying a pre-call step. It does not explicitly state when not to use it versus write_update_card or other write tools, so it stops short of a full exclusionary usage guide.

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

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

Annotations already mark readOnly=false and destructiveHint=true, but the description adds materially valuable behavior: role effort rows are written instead of card totals, task efforts roll up and overwrite the parent story's value, and parent before/after values are reported. This tells an agent exactly what side effects to expect. No contradiction with the annotations.

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

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

Every sentence earns its place: the first states purpose, the second clarifies the write target, and the third discloses roll-up and reporting behavior. The description is front-loaded and appropriately dense for a mutating tool.

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 two parameters, no output schema, and destructive annotations, the description covers the important operational facts: required role, per-role array, no card-total writes, roll-up overwrite, and reported before/after values. There is enough information for an agent to decide whether to call it and anticipate 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?

The schema describes role and effort values inside the nested efforts array, but does not explain what id refers to; the description's 'on a card' supplies that missing context. It also reinforces array semantics ('one or more roles') and the required-role constraint. It doesn't enumerate format rules beyond that, but the schema already carries the value details.

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

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

States a specific action ('Set effort') on a well-defined resource ('one or more roles on a card') and goes beyond the name by distinguishing RoleEffort rows from the card total that Targetprocess computes. This makes the tool's purpose unmistakable and separates it from generic card-update or time-logging siblings.

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

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

Provides clear usage context: call it when setting role-specific efforts, requires a role, and explicitly says it never writes the card total. It also warns about roll-up into the parent user story, which signals when those side effects matter. It stops short of naming an alternative sibling for card-total updates, so it doesn't quite hit the explicit alternatives bar.

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

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

Annotations provide readOnlyHint=false and destructiveHint=true, so the write/destructive nature is known. The description adds valuable beyond-annotation behavior: state read-back (confirms the result read back), and the side-effect that moving a task out of its initial state can advance its user story (parent card state before/after reported). For a destructive write tool, this side-effect disclosure is valuable context. It doesn't cover rollback or reversibility, but with only a 3-param schema and moderate complexity, this is solid.

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, clearly front-loaded with the core action, then team variant, then side-effect and read-back. Zero filler, every clause carries meaning.

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

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

For a write tool with no output schema, the description covers the action, resolution semantics, team behavior, read-back, and the parent-card side-effect. It doesn't explain error cases or permissions, but given the moderate complexity and the rich sibling context, it's nearly complete. Missing per-team caveats or condition of 'initial state' are minor.

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

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

Schema description coverage is 67% – the schema covers 'team' and 'state' param semantics (state: 'State name or id', team: 'Team whose team state to set'), but not 'id'. The description adds meaning to 'state' (resolved by name or id against card's own project workflow) and adds the team nuance (sets team's state on card, or project workflow when team has none). It partially compensates for the gap on 'id' by clarifying resolution context, but doesn't explicitly document 'id' semantics beyond schema. Given substantial added meaning, 4 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 states a specific verb ('Move') and resource ('a card to a state'), and explains resolution against the card's own project workflow, distinguishing it from siblings like write_update_card or write_assign. It also adds a team-specific behavior (team sub-workflow or project workflow) that makes its purpose unique and concrete.

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

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

The description implies when to use it: to set/move a card's state, with team variant for team states. It doesn't explicitly name a when-not or alternative (e.g., write_update_card for other card updates), but the semantic clarity of 'move to state by name or id' plus the team sub-workflow guidance provides clear context. Lacks explicit exclusions, hence 4 rather than 5.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=true), the description discloses critical behaviors: null values delete keys, existing keys are preserved, missing groups/keys are created, and only owners/admins can change scope or publicData. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is three tightly packed sentences with no filler. The core operation is stated first, followed by the essential merge rules and permission constraints, and every sentence adds necessary information.

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

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

Given the tool has no output schema and nested object parameters, the description covers the key operational details: create/update behavior, merge/deletion semantics, automatic creation of missing groups/keys, and ownership restrictions. Nothing an agent needs to invoke the tool correctly is missing.

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

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

With only 20% schema description coverage, the description compensates well by explaining how userData/publicData keys are merged, how null deletes keys, and how missing groups/keys are created. However, it does not elaborate on the meaning of 'scope' beyond the enum values or describe the key semantics beyond the schema's pattern.

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

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

The description opens with 'Create or update a storage entry,' a specific verb and resource that clearly distinguishes this tool from read_storage, delete_storage, and generic write_create/write_update tools. The MERGE semantics further clarify exactly what kind of mutation this performs.

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

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

The description gives clear context by framing the tool as the write path for storage entries and explaining the merge behavior, so an agent knows this is the tool for creating or updating storage entries. It does not explicitly exclude alternatives or name when-not-to-use conditions, but the context is strong enough to route correctly.

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

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

Annotations already signal destructive behavior and non-read-only intent. The description adds meaningful behavioral context beyond the annotations: adding appends rather than replaces, and removing deletes only the named team assignment. This gives an agent a clearer model of the mutation's semantics without contradicting the annotations.

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

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

The description is two short, front-loaded sentences with no filler. The first sentence states the core operation, and the second adds only the behavioral caveat needed to prevent misuse.

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 three-parameter mutation with destructiveHint and no output schema, the description covers the action, accepted value types, and key mutation semantics. The main gap is identifying the required 'id' parameter, but the phrasing 'from a card' makes the card context reasonably clear, and the annotations cover the safety profile.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that add/remove items may be team names or ids, which helps disambiguate the string/integer unions in the schema. However, it never explicitly explains that the required 'id' parameter refers to the target card, nor how add and remove interact when both are provided.

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

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

The description names a specific verb (add/remove) and a specific resource (teams on a card), and clarifies that identifiers can be names or ids. This clearly distinguishes it from sibling tools like write_assign or write_update_card, which target different resources or 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 implies when to use the tool: any time team assignments on a card need to be added or removed. It also gives useful behavioral guidance about appending vs deleting. However, it does not explicitly contrast this with write_assign/write_unassign or say when one should be preferred over the other.

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

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

Annotations already cover readOnlyHint=false and destructiveHint=true, so the description needn't restate that this is a write operation. It adds useful behavior: 'Each case is read back' and clarifies project inheritance. It does not explain the implications of destructiveHint, but there is no contradiction.

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

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

Three short sentences, each serving a distinct purpose: the action, the project inheritance rule, and the read-back behavior. There is no filler or redundancy.

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

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

For a write tool with 0% schema coverage, no output schema, and a nested cases array, more context is needed: how to represent ordered steps, how testPlan is supplied, and what constraints apply. 'Each case is read back' gives only a vague hint of the response.

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

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

Schema description coverage is 0%, so the description must compensate, but it only mentions 'test plan,' 'cases,' and 'ordered steps.' It does not explain the testPlan ID format, how the steps array is structured, or the 1-100 item limit. Minimal semantic value beyond the property names.

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

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

The description states a clear verb and resource: 'Create test cases with ordered steps under a test plan.' It also adds the inherited project detail, which distinguishes it from general write tools. However, it does not explicitly differentiate it from sibling tools like write_test_run or write_create_card.

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?

There is no explicit guidance on when to use this tool versus alternatives. The phrase 'under a test plan' implies context, but no when/when-not conditions or sibling comparisons are provided.

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

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

The description adds meaningful behavioral context beyond the annotations: creating a test plan run, auto-adding a 'Not run' test case run per case, and then setting results with optional comments. It does not contradict the readOnlyHint=false or destructiveHint=true annotations.

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

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

The description is a single compact sentence that front-loads the purpose and then explains the effects. The parenthetical status list is slightly redundant with the schema, but it improves quick comprehension without bloating the definition.

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 definition is adequate for selecting and invoking the tool for the core workflow, and it exposes an important side effect. It leaves some gaps around repeated calls, overwriting behavior, and return values, and no output schema is present to fill those gaps.

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

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

With 0% schema description coverage, the description compensates for the main parameters: it clarifies the testPlan relationship, the result statuses, and the optional comment. It does not explain the optional name parameter or the testCase identifier format, leaving part of the parameter surface undocumented.

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 names a specific action and resource: recording a test run of a test plan and setting test case results. It clearly distinguishes this from sibling tools like write_test_cases by explaining the two-step 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 opening phrase implies the intended use case: record a test run and its results. However, it does not explicitly say when to prefer this over related tools like write_test_cases or state prerequisites such as the test plan already existing.

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

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

Annotations already declare destructiveHint=true, so the description doesn't need to restate that. It adds useful behavioral context: the operation is exact and targets a person+role pair, with a conditional requirement on role. However, it does not disclose return/error behavior or what happens if no matching assignment exists.

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

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

Two sentences, no filler, with the core action front-loaded and the conditional rule in a compact follow-up. Every clause 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 3-parameter destructive tool with helpful annotations and schema descriptions, the description supplies enough to select and invoke it correctly. Minor gaps remain around error handling and the exact behavior when role is omitted, but they are not critical given the annotations.

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

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

The schema already documents user and role with examples (67% coverage), and the description adds meaning by framing the operation as removing a person+role assignment from a card and explaining when role is required. The id parameter is still not described explicitly, but the card context makes its role reasonably clear.

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 action verb ('Remove') and a precise resource ('one exact assignment (person + role) from a card'). This clearly differentiates it from write_assign and write_set_role_effort, and the role condition further pinpoints its exact 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?

It gives a clear operational rule: when the person holds several roles on the card, the role is required. It does not explicitly mention sibling alternatives or when-not-to-use cases, but the context is clear enough for an agent to know when this tool applies.

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

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

The description adds substantial behavioral context beyond the annotations: values are 'validated against the catalog before sending', the response is read back and non-persisted values are reported, and writing Effort bypasses role efforts. These disclose real side-effect and verification behaviors. The destructiveHint=true and readOnlyHint=false annotations are consistent with the described write behavior. The unexplained 'layer 1' phrase slightly detracts, since it obscures rather than clarifies scope.

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

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

Three sentences, each earning its place: the primary action with validation, the read-back verification behavior, and the alternative routing. The main action is front-loaded ahead of caveats, with zero redundancy or filler.

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

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

The description covers key runtime behavior — validation, persistence verification, and the Effort trap — which partially compensates for the missing output schema. But it leaves 'layer 1' undefined, does not clarify the boundary with write_update_card, and says nothing about error handling or authorization. For a destructiveHint=true tool with no output schema, a bit more context would be expected.

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

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

Schema description coverage is 67%, with resource and fields already documented in the schema (including a Targetprocess JSON example for fields). The description adds some semantic nuance — the Effort-bypass warning applies to the fields parameter — but it does not materially explain id or resource beyond what the schema provides. The schema carries the primary burden, so the baseline 3 is appropriate.

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

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

The description states a specific action ('Update fields of an existing entity') with a resource and scope. It distinguishes itself from one sibling explicitly ('use write_set_role_effort instead'). However, the qualifier '(layer 1)' is opaque — an agent has no way to know what layer 1 means or whether layer 1 is the right layer — and the description does not differentiate from closely named siblings like write_update_card or write_set_custom_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 Effort caveat provides an explicit when-not-to-use rule with a named alternative ('Writing a card Effort here bypasses role efforts; use write_set_role_effort instead'). The general use case (updating fields on an existing entity) is clear. It does not, however, discuss when to prefer write_update_card, write_set_custom_fields, or write_create, which are plausible competitors in the sibling list.

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