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

Even though annotations exist, the description adds substantial behavior beyond them: atomic all-or-nothing validation ("one invalid item means nothing is sent"), dry_run semantics, parking inheritance rules, rate limiting ("Writes run 4 at a time"), partial-failure error semantics, and explicit retry guidance with the duplicate-warning. No contradiction with annotations — readOnlyHint=false and idempotentHint=false align with the warning that resending the whole call duplicates created bars.

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 long but every block earns its place: USE WHEN, single-bar alternative, item requirements, set semantics, atomicity, dry_run, parking, rate limits, return format, retry guidance, and FAILS WHEN. Clear structural markers make it scannable, and the core purpose is front-loaded in the first sentence. Slightly dense, but no wasted words.

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

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

For a complex bulk-write tool with nested objects, no output schema, and 4 parameters, the description is remarkably complete. It covers the return value explicitly (per-item result objects and summary string) since there is no output schema, plus error semantics, validation behavior, retry strategy, and failure conditions. Nothing an agent needs to call this safely and 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it clarifies the lane resolution rule (lane from the item OR from set, and by name or lane_id), gives a concrete set example, states the 100-item cap, and cross-references fields to manage_bar create. The dry_run parameter gains precision ("returns the exact POST payloads") beyond the schema's wording.

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 first sentence states a specific verb, resource, and scope: "Create many bars on one roadmap in one call." It names the sibling it is routing away from (manage_bar) and is unmistakably distinct from the other sibling alternatives (bulk_update_bars, bulk_delete_bars). An agent can tell exactly what this tool does without opening 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 provides an explicit USE WHEN block with concrete natural-language triggers ("Add these 20 features to the roadmap", "Import this list as bars") and a direct exclusion: "For a single bar, use manage_bar instead." It also implies when NOT to use it vs. the update/delete bulk siblings by naming the operation as create-only. Routing guidance is fully 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses rich behavioral details: it verifies each delete by reading the bar back expecting 404, runs deletions 4 at a time under the client's rate limiter, reports per-item results, and returns an error only when no bar was deleted. It also warns that deletion is permanent and cannot be undone, which aligns with and expands on the destructiveHint 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 thorough but well-organized with labeled sections (USE WHEN, FAILS WHEN, WARNING) and front-loaded purpose. Every sentence adds value, covering usage, constraints, verification, concurrency, and error reporting. While it is long, the complexity of a destructive bulk operation justifies the detail; it is not padded with fluff.

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

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

For a destructive bulk operation with no output schema, the description is exceptionally complete: it explains when to use it, parameters, failure modes, return format (per-item {index, bar_id, ok, error} and summary example), concurrency, rate limiting, and verification behavior. An agent has all the information needed to call it correctly and interpret the result.

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

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

The input schema already describes all three parameters, but the description adds critical semantics: it clarifies that confirm is mandatory for actual deletion (even though not marked required in the schema), explains the dry_run behavior in detail (looks up bars and returns names without deleting), and imposes constraints on bar_ids (up to 100, each once). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Permanently delete many bars in one call, verifying each delete.' It specifies the verb (delete), resource (bars), and scope (many bars in one call). It also distinguishes from the single-bar alternative by explicitly naming manage_bar action=delete, so an agent can immediately tell them apart.

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

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

The description provides explicit usage guidance with a 'USE WHEN' section listing example user intents and a direct exclusion: 'For a single bar, use manage_bar action=delete instead.' It also explains when confirm and dry_run are appropriate, and describes failure conditions under 'FAILS WHEN.' This leaves no ambiguity about when to select this tool.

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

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

The description reveals behaviors beyond annotations (which only signal destructiveHint=true): validation before any write ('One invalid item means nothing is sent'), dry_run returning exact payloads without writing, 4-at-a-time writes under the client's rate limiter, per-item result format, and the nuance that an error only occurs when no bar is updated (partial failures are normal results with retry guidance). It also flags unsupported fields (legend_id, effort) routed to manage_bar. This is comprehensive behavioral disclosure.

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

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

The description is longer than typical but front-loads the purpose and use cases before the detailed operation semantics. Every sentence contributes to operational correctness — override logic, validation, dry run, rate limiting, failure handling. It is dense but not padded; slightly tighter could be achieved without losing value, but the length is justified by the bulk-write 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 usage, validation, error semantics, retry behavior, dry run, concurrency, capacity limits, and return format. With no output schema present, it explicitly states the per-item result structure and summary format. It also addresses rate limiting and the optimization via roadmap_id. No critical gap remains 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?

Though the schema documents all 4 parameters (100% coverage), the description adds critical semantics: set vs items override behavior ('an item's own fields override set'), the capacity limit (up to 100 items) and uniqueness constraint (each bar_id may appear once), and how roadmap_id skips per-bar roadmap lookups. It also clarifies dry_run and the per-item roadmap_id field. These are material additions beyond the schema descriptions.

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

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

The description states a specific verb and resource ('Update many bars in one call') with concrete operation examples (recolor, move lanes, retag, reschedule, set progress). It explicitly distinguishes itself from the single-bar sibling manage_bar and from other bulk tools in the sibling list. The purpose is unambiguous and uniquely identifiable.

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 includes a 'USE WHEN' block with example user phrases and explicitly routes single-bar cases to manage_bar. It also enumerates 'FAILS WHEN' conditions, giving clear operational boundaries. This is explicit when-to-use, when-not-to-use, and alternative tool 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 readOnlyHint=true, so the safety profile is known. The description adds meaningful context by specifying that this checks both connectivity status and authentication, and clarifies the boundary against health_check. With no destructive behavior and an output schema present, the description sufficiently covers 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 compact and front-loaded with the core purpose, followed by concise usage triggers and a clear pointer to the alternative. Every line earns its place with no redundant detail.

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

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

For a parameterless status-check tool with an output schema and readOnlyHint annotation, this description is fully complete. It tells the agent what the tool does, when to use it, and when to choose health_check instead, leaving no critical 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?

The tool has zero parameters, and schema description coverage is 100%, so there is nothing for the description to add about parameter meanings. The baseline for a no-parameter tool is 4, and the description does not need to compensate for any schema gaps.

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

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

The description states a specific action—checking ProductPlan API status and authentication—on a clear resource. It also names the sibling health_check as a different tool for server internals, distinguishing this tool from the most likely confusable 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 explicitly provides USE WHEN examples ('Is ProductPlan connected?', 'Check API') and a clear exclusion: for MCP server internals like cache stats and rate limits, use health_check instead. This gives an agent unambiguous 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 mark the call read-only; the description adds the failure mode for a missing bar_id and directs the agent to fetch valid IDs from get_roadmap_bars. It also explicitly lists the returned data, giving useful behavioral context beyond the structured 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 compact and well-structured with USE WHEN and FAILS WHEN sections. It loses a point because 'including description, links, custom fields' is largely redundant with the fuller return-field list that follows.

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 read-only lookup with an output schema and 100% schema coverage, the description covers the trigger phrases, the input source, the failure mode, and the returned fields. Nothing essential for correct invocation 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 100% schema description coverage, the schema already documents bar_id as 'Bar ID from get_roadmap_bars'. The description repeats this same source hint, reinforcing it but adding no new format, validation, or behavioral detail, so the baseline score of 3 applies.

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

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

The description clearly identifies a specific verb and resource ('Get bar details') and enumerates the returned fields (name, dates, links, custom fields, percent_done, lane info), making the tool's purpose obvious. It does not explicitly contrast this tool with nearby getter siblings like get_bar_children or get_roadmap_bars, so it lacks full sibling differentiation.

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 WHEN' section gives concrete user intents and phrases that should route an agent here, and 'FAILS WHEN' identifies the main error condition. It also points to get_roadmap_bars as the source of valid IDs, but it does not state when a sibling getter should be preferred.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds valuable behavior beyond annotations: it returns an empty list for non-container bars and fails when bar_id is not found. This is useful, though it doesn't discuss auth or rate limits.

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: one core sentence, then USE WHEN and FAILS WHEN sections. No filler or repetition. Every sentence contributes actionable 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 simple read-only tool with one parameter and an output schema, the description covers the essential selection cues, failure behavior, and empty-result edge case. Nothing critical for calling this 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?

Schema coverage is 100% for the single parameter, with bar_id already described as 'Parent bar ID.' The description does not add extra parameter-level meaning, so 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 verb and resource: 'Get child bars nested under a parent bar.' This clearly distinguishes it from sibling tools like get_bar, get_bar_links, and get_bar_comments. The scope is immediately understandable.

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 WHEN section gives concrete trigger phrases like 'Show sub-tasks' and 'Break down this feature,' which helps an agent select this tool. It also notes a failure mode. It does not explicitly name alternatives or when not to use it, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds a valuable behavioral detail: the tool fails when bar_id is not found, which is not captured in annotations or schema. This extra failure mode disclosure goes beyond the structured metadata, though it doesn't detail return format or pagination (likely covered by output schema).

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

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

The description is extremely concise, with a one-line purpose, a clear 'USE WHEN' block, and a 'FAILS WHEN' block. No wasted words. The main purpose is front-loaded, and the usage guidance is immediately actionable.

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 tool with one parameter and an output schema, the description covers all necessary aspects: what it does, when to use it, what to use instead, and a known failure condition. The output schema handles return format, so nothing critical 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?

Schema description coverage is 100% (bar_id has a description 'Bar ID'), so the schema already documents the parameter. The description does not add additional meaning about bar_id, but given the high coverage, the baseline of 3 is appropriate. The tool name and description context make the parameter's role 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 clearly states the verb and resource: 'Get comments on a bar.' It also distinguishes itself from the closely related sibling get_roadmap_comments by explicitly saying to use that tool for roadmap-level comments. This makes the purpose unmistakable and differentiates it from similar get_* tools.

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

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

The description provides explicit 'USE WHEN' triggers with example user phrases and names the alternative tool for a different scenario (roadmap-level comments). It also includes a 'FAILS WHEN' condition (bar_id not found). This gives clear, actionable guidance on when to choose this tool over siblings.

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

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

Annotations declare readOnlyHint=true, indicating a safe read operation. The description adds that it returns an empty list when no connections exist and fails when bar_id is not found, which are useful behavioral details beyond the annotation. It does not contradict annotations and adds practical context for error handling.

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

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

The description is extremely concise: a one-line purpose followed by USE WHEN and FAILS WHEN sections. Every word serves a purpose, and the key information is front-loaded. There is no fluff or redundancy, making it easy for an agent to parse quickly.

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

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

For a simple tool with a single parameter and an output schema present, the description covers the essential points: what it does, when to use it, and failure behavior. It does not explain the exact structure of the returned dependencies, but since an output schema exists, that is not required. It is sufficiently complete for correct invocation.

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

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

The schema already documents bar_id with description 'Bar ID' and 100% coverage, so the baseline is 3. The description does not add any further detail about the parameter's format or meaning, but it doesn't need to since the schema is sufficient. No extra value provided 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 states a specific verb and resource: 'Get bar dependencies (what blocks what).' It clearly distinguishes the tool from siblings like get_bar (which fetches a bar), get_bar_children (which gets children), and get_bar_links (which gets links), making its 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 includes 'USE WHEN' cues with example user intents ('What depends on this?', 'Show dependencies'), providing clear context for when to invoke it. It also notes failure behavior (bar_id not found) and empty-list return, which helps agents decide if this is the right call. It does not explicitly list alternative tools to avoid, but the usage cues are adequate.

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

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

Beyond the readOnlyHint annotation, the description discloses two failure/behavior traits: it fails when bar_id is not found and returns an empty list when there are no external links. This is useful behavioral context that an agent would not otherwise know.

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 purpose-built lines: the core action, a USE WHEN trigger, and a FAILS WHEN condition. Every sentence contributes, and the core action 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 single-parameter read-only lookup with an output schema, the description covers the essential usage triggers and edge cases. Nothing material is missing 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?

The schema already documents bar_id with 100% coverage, so the baseline applies. The description mentions 'bar_id not found' but does not add format, source, or usage details beyond the schema's 'Bar ID'.

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 sentence names a specific verb ('Get'), resource ('external links on a bar'), and gives concrete link categories ('Jira, docs, designs'), making the tool's purpose unmistakable. This also differentiates it from similar get_* siblings by scoping it to external links rather than connections, comments, or general bar 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 explicit 'USE WHEN' section gives trigger phrases ('What's linked?', 'Show Jira tickets') that an agent can match to user intent. It does not enumerate alternatives or when not to use the tool, but for a simple lookup this is clear contextual guidance.

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

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

Annotations already mark this as readOnlyHint=true, and the description adds useful failure behavior ('FAILS WHEN: idea_id not found'). With an output schema present, no return-format disclosure is needed. It could add more detail about metadata contents, but the core behavioral context is clear.

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: purpose first, then explicit use and failure guidance. No filler or redundant restatement 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 one-parameter read tool, the description covers what it does, when to use it, and how to avoid failure. Combined with the output schema and readOnlyHint annotation, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, with idea_id already documented as 'Idea ID from list_ideas'. The description reinforces this source but adds no additional parameter semantics beyond the schema.

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

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

The description uses a specific verb and resource ('Get idea details including description and metadata') and is clearly distinguishable from sibling tools like get_idea_form or manage_idea. It tells an agent exactly what object is being retrieved.

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

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

Provides explicit USE WHEN triggers ('Tell me about this idea', 'Full request details') and a FAILS WHEN condition. It also routes to list_ideas for valid IDs, though it does not contrast with similar getters like get_idea_form.

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

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

Annotations declare readOnlyHint=true, so the description does not need to restate that it's read-only. The description adds context about typical user queries (showing form fields) and failure conditions, which is useful. However, it does not disclose details about the response structure or potential errors beyond the mention in FAILS WHEN, which is acceptable given the output schema exists.

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

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

The description is very brief and front-loaded with the core purpose. The USE WHEN and FAILS WHEN sections are tersely phrased and each sentence adds value. No fluff or unnecessary 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 tool is simple with one parameter, an output schema, and read-only annotation. The description covers the essential use case and failure handling. It could mention that the returned data includes form fields, but the description already says 'with fields'. Given the simplicity, it is nearly complete.

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

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

The schema has 100% coverage; the only parameter 'form_id' is well-described as 'Form ID from list_idea_forms' in both schema and description. The description adds a hint about obtaining valid IDs from list_idea_forms, which is slightly redundant but confirms the origin. The description adds minimal extra meaning beyond the schema, so a 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 the tool retrieves idea form details with fields, indicating a read operation. It is distinct from sibling 'list_idea_forms' which likely lists forms, but the description does not explicitly differentiate from other get_* tools. However, the specific resource and action are 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 includes an explicit 'USE WHEN' section listing example user queries, and a 'FAILS WHEN' section that tells the agent what to do if the form_id is not found, directing to list_idea_forms for valid IDs. This provides clear guidance on when to use and how to handle failure.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the failure condition (not found) and the alternative, which is useful context beyond the annotations. It doesn't describe response format or edge cases, but for a simple read operation, this is adequate.

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

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

The description is extremely concise: a single sentence plus two labeled lines for USE WHEN and FAILS WHEN. It front-loads the purpose and provides actionable guidance with zero waste.

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

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

The tool is a simple read operation with an output schema. The description covers usage, failure modes, and alternative sourcing of IDs. Given the annotations and output schema, nothing critical is missing. It lacks explicit mention of return format, but the output schema likely covers that.

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%: both objective_id and key_result_id are described as 'Parent objective ID' and 'Key result ID' respectively. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states 'Get key result details,' which is a specific verb+resource. It clearly indicates retrieving details of a key result, distinguishing it from list_key_results (which lists) and manage_key_result (which mutates). However, it doesn't explicitly name the sibling it is not, though the resource is distinct from get_objective.

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

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

The description provides explicit USE WHEN phrases ('Tell me about this KR', 'KR progress') and FAILS WHEN conditions, directing the agent to list_key_results for valid IDs. This fully covers when to use and what to do if it fails, and implicitly excludes alternatives.

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

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

Annotations already establish readOnlyHint=true, so the description does not need to restate safety. It adds useful behavioral context beyond the schema by disclosing the failure mode when launch_id is not found and directing the agent to list_launches for valid IDs. This is meaningful added value for a read-only tool.

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

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

The description is compact and front-loaded: a one-line purpose statement, followed by USE WHEN and FAILS WHEN triggers. Every sentence earns its place, and there is no fluff or redundant elaboration.

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

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

For a single-parameter read-only tool with an output schema, the description covers the essential context: what the tool returns, when to invoke it, and what to do when the ID is invalid. The agent has enough information to call this tool correctly without consulting additional documentation.

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

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

There is only one parameter and the schema already describes it as 'Launch ID from list_launches' with 100% coverage. The description repeats the same ID-source guidance without adding format, constraints, or additional behavioral meaning, so it does not exceed the schema baseline.

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

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

The description states a clear verb and resource: 'Get launch details with checklist.' It is clearly a launch-level read operation, but it does not explicitly contrast itself with sibling tools like get_launch_sections or get_launch_tasks, so some sibling differentiation is left to inference.

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 WHEN section gives concrete natural-language triggers ('Tell me about this launch', 'Launch readiness'), and FAILS WHEN warns about invalid IDs while pointing to list_launches as the ID source. It provides clear usage context but does not mention when to prefer an alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safe read behavior is covered. The description adds a useful behavioral detail beyond annotations: the tool fails when launch_id or section_id is not found. This is meaningful context for error handling.

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

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

The description is short and well-structured with USE WHEN and FAILS WHEN sections. The quoted use case is slightly redundant with the opening sentence, but the sibling routing and failure disclosure earn their place.

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

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

With a 100% documented schema, an output schema, readOnlyHint annotation, and explicit sibling differentiation, nothing essential is missing. The agent knows what the tool does, when to use it, when it fails, and where to route for the plural case.

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 both launch_id and section_id are already documented in the schema. The description only repeats the 'by ID' concept and the failure condition; it does not add new parameter-level meaning.

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

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

The description uses a specific verb and resource: 'Get a specific checklist section by ID.' It also explicitly distinguishes this tool from the sibling get_launch_sections, making its scope 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?

It provides an explicit USE WHEN condition, names the alternative for fetching all sections (get_launch_sections), and gives a FAILS WHEN condition. An agent can confidently decide between this and its sibling without extra 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?

The annotations already mark the tool as readOnlyHint=true; the description adds the behavioral disclosure that the call fails when launch_id is not found. This goes beyond the schema and annotations by warning the agent about a non-empty error case rather than assuming an empty result.

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 line earns its place: the purpose, trigger phrases, alternative routing, and failure condition. It is compact, front-loaded, and contains no filler or redundant restatement 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 single-parameter, read-only listing tool with an output schema and explicit alternative routing, the description covers what an agent needs: what to call it for, when to use it, when it makes sense to call the sibling, and the primary failure mode. Nothing essential is missing.

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

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

Schema description coverage is 100% and the only parameter, launch_id, is described as 'Launch ID'. The main description adds no new meaning beyond that, which is acceptable since the schema already fully documents the 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 opens with a specific verb and resource: 'Get checklist sections for a launch.' It explicitly distinguishes itself from get_launch_section by noting that the singular tool is for one specific section, so an agent can immediately tell the two apart.

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

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

It provides explicit USE WHEN trigger phrases ('Show sections', 'Checklist categories'), names the alternative (get_launch_section), and states the condition under which it should be used instead. It also documents a failure condition, leaving little 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 the description adds a concrete failure mode (not found) beyond the structured data. While it doesn't discuss output or edge cases further, the safe read-only behavior is already covered; the description contributes the failure condition and the scoping distinction, which is sufficient for a simple getter.

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 structured with labeled sections (USE WHEN, FAILS WHEN). The core purpose is front-loaded in the first sentence, and every sentence earns its place by either clarifying usage or warning about failure. No redundant content.

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

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

For a two-parameter getter with an output schema and readOnlyHint, the description covers purpose, usage, sibling routing, and failure conditions. Nothing an agent needs to invoke it correctly is missing—the output schema handles return details, and annotations handle 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 100%, so both parameters are already documented as 'Task ID' and 'Launch ID'. The description adds no additional semantics (e.g., relationship, format, or required combination). Given full schema coverage, the baseline of 3 is appropriate—the description doesn't need to compensate.

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 specific action ('Get') and resource ('launch task'), and explicitly differentiates from the sibling get_launch_tasks by saying 'For all tasks, use get_launch_tasks.' This leaves no ambiguity about which tool to select for a single task lookup.

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

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

Provides explicit USE WHEN triggers (single task by ID, check assignment/status) and directly routes the agent to the sibling get_launch_tasks for all-tasks queries. The FAILS WHEN clause also sets expectations for error conditions, giving clear context on when not to rely on this tool.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the failure condition (launch_id not found) and the collection-level scope, which is useful context. However, it doesn't disclose what happens on failure (error message? empty list?) or whether the response is ordered/paginated. 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 compact and front-loaded: the core purpose is in the first sentence, followed by structured USE WHEN and FAILS WHEN sections. Every sentence earns its place, and the formatting makes the guidance scannable for an agent.

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 one parameter, an output schema, and annotations covering safety, the description is nearly complete. It covers purpose, usage context, alternative, and failure condition. The only minor gap is not describing the return format, but the output schema presumably handles that, so the description doesn't need to.

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% — the only parameter launch_id is documented in the schema as 'Launch ID'. The description doesn't add meaning beyond that, but it doesn't need to since the schema fully covers the single parameter. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Get all tasks for a launch.' It clearly identifies the collection-level operation and distinguishes it from the sibling get_launch_task by noting the single-task alternative. It doesn't explicitly name the sibling in the main description, but the USE WHEN/FAILS WHEN structure provides enough differentiation.

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

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

The description provides explicit usage guidance: USE WHEN with example user queries ('Show tasks', 'What needs to be done?'), a clear alternative for a different case ('For one specific task, use get_launch_task'), and a failure condition ('FAILS WHEN: launch_id not found'). This is exactly the kind of when-to-use vs alternatives guidance that helps an agent select 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 declare readOnlyHint=true, so the safety profile is covered. The description adds the failure behavior when objective_id is not found, which is useful. However, it does not disclose other behaviors such as response structure or potential pagination, but given annotations, the added failure info earns a 3.

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 with a front-loaded purpose statement followed by clearly labeled USE WHEN and FAILS WHEN sections. Every line adds value without redundancy, making it easy to scan.

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 read-only tool with an output schema (indicated), the description covers the purpose, usage triggers, failure mode, and ID sourcing. It doesn't explain return format, but the output schema handles that, so the description is adequately complete.

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

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

Schema description coverage is 100% with 'Objective ID from list_objectives' in the parameter description. The tool description essentially repeats this in the FAILS WHEN note, adding no new semantics beyond the schema. Baseline of 3 applies since the schema fully documents the 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 clearly states the tool retrieves objective details including key results, which specifies the verb and resource. It differentiates from sibling tools like get_key_result by mentioning 'objective details with key results', making its scope clear even without listing every 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?

Provides explicit USE WHEN examples ('Tell me about objective X', 'OKR progress') and a FAILS WHEN condition for invalid objective_id, pointing to list_objectives for valid IDs. This gives clear usage context and a fallback source, though it doesn't explicitly exclude alternative tools like get_key_result.

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

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

Annotations already declare readOnlyHint=true, so the description's 'Get' aligns with that. The description adds the failure mode (opportunity_id not found) and suggests sourcing valid IDs, which is useful context beyond the annotations, but it doesn't describe other behavioral traits like response format or any side effects.

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

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

The description is extremely concise: two sentences plus a USE WHEN and FAILS WHEN clause. Every element serves a purpose, and the main purpose is front-loaded. No wasted words.

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

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

For a simple single-parameter getter with an output schema, the description covers the essential usage context and failure condition. It lacks details on what 'linked ideas' means or what the response contains, but the output schema presumably covers that. It is adequately complete for a tool of this complexity.

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

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

Schema description coverage is 100% and the schema already describes opportunity_id as 'Opportunity ID from list_opportunities'. The description doesn't add additional semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the verb 'Get' and the resource 'opportunity details', and adds 'with linked ideas' which distinguishes it from generic getters. However, it doesn't explicitly differentiate from siblings like get_idea or get_launch, so it stops short of a 5.

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

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

The description provides explicit USE WHEN and FAILS WHEN clauses, including guidance to get valid IDs from list_opportunities. This gives clear context on when to invoke the tool, though it doesn't mention alternative tools for comparison.

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

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

Beyond the readOnlyHint annotation, the description explains what the call returns and that the returned vocabulary (legends, lanes, custom fields) is exactly what manage_bar and bulk_*_bars tools validate against. It also discloses the failure mode for missing roadmap IDs, adding genuinely useful behavioral context.

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

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

The description is well-structured into clear sections with no filler. The core purpose is front-loaded, and each section—USE WHEN, alternative, return content, FAILS WHEN—earns its place without 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 read-only settings/metadata tool with a single fully-documented parameter and an output schema, the description covers everything an agent needs: purpose, usage context, sibling differentiation, failure behavior, and prerequisite. Nothing critical is missing.

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

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

The schema already fully documents roadmap_id with 100% coverage, so the baseline is 3. The description adds value by explicitly instructing the agent to obtain valid IDs from list_roadmaps first and by stating the failure condition when the ID is not found, reinforcing the parameter's provenance and validation expectations.

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 roadmap settings and metadata,' a specific verb and resource. It differentiates from the sibling get_roadmap_complete by explicitly limiting scope to settings/metadata, and the USE WHEN examples make the tool's purpose unmistakable.

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

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

Provides explicit USE WHEN examples and names the alternative get_roadmap_complete for cases needing all data in one call. The FAILS WHEN section identifies the prerequisite of getting valid IDs from list_roadmaps first, giving clear selection and sequencing 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?

Beyond the readOnlyHint annotation, the description discloses behavior an agent could not infer: the 50-item cap, that client-side filters apply 'to every fetched bar, before the 50-item cap,' that date filters are inclusive, that client-side filters are exact and case-insensitive, and the exact no-results message. These are genuine behavioral disclosures that materially affect how the agent should invoke the tool.

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

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

The description is long, but every section earns its place: purpose first, then USE WHEN triggers, then filter semantics grouped by execution site, then return fields, then FAILS WHEN. The labeled sections (USE WHEN / FAILS WHEN) make it scannable, and for an 11-parameter tool with complex filter behavior, the density is justified rather than padded.

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 11-parameter complexity, this description is complete: it covers failure modes, alternative routing for both more detail (get_bar) and roadmap discovery (list_roadmaps), filter semantics, ordering with the 50-item cap, and return fields — even though an output schema exists so return-value explanation wasn't required. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it groups the 11 parameters into server-side vs client-side filters and explains the practical consequence of that split (where they are applied, ordering with the 50-item cap, exactness). This explains the sort pattern's meaning, the allowed field list, and date inclusivity, which goes beyond what the schema's per-parameter descriptions state.

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

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

The description opens with a specific verb+resource: 'Get bars (features/items) on a roadmap, optionally filtered.' It distinguishes itself from siblings by explicitly routing detail lookups to get_bar ('For a bar's description and custom fields, use get_bar'), and the sibling list shows get_roadmap_bars sits apart from get_bar, get_bar_children, and get_roadmap_complete. An agent can tell exactly what this tool does and what it does not do.

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 WHEN' section gives concrete user-intent examples ('What's on the roadmap?', 'What's starting in Q2?', 'Bars in the Mobile lane tagged urgent'). The 'FAILS WHEN' section names failure triggers and routes to alternatives ('roadmap_id not found (use list_roadmaps)'). This is explicit when-to-use guidance with exclusion and 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 cover readOnlyHint=true, so the description need not restate read-only behavior. It adds a failure condition (roadmap_id not found) and suggests list_roadmaps, plus specifies the return array shape (author, body, timestamp). No contradictions 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 compact and well-structured: a clear primary statement, usage trigger, alternative, return format, and failure mode. Every sentence adds value with no redundancy.

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

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

With only one parameter, a read-only annotation, an existing output schema, and clear sibling differentiation, the description covers usage, alternative, failure, and return shape. No critical information is missing for correct invocation.

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

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

Schema description coverage is 100% for roadmap_id, so the schema already documents its meaning. The description adds no new parameter semantics beyond the failure condition, which is more behavioral than semantic. Baseline 3 applies.

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

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

The description clearly states the verb 'Get' and the resource 'roadmap-level comments', and explicitly contrasts with bar comments, distinguishing it from the sibling get_bar_comments. This gives an unambiguous 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?

It provides explicit trigger phrases like 'Show roadmap comments' and 'Roadmap discussion', and names the exact alternative (get_bar_comments) for bar-level comments, making the selection criteria unambiguous.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context beyond that: it is a combined aggregation call, it returns multiple data categories in one response, and it fails when the roadmap_id is missing. This is useful complementary transparency, though auth and rate-limit details are not mentioned.

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 and compact, with clear USE WHEN and FAILS WHEN sections. However, the opening sentence and the later sentence both repeat the same combined-return information, creating minor redundancy that prevents a perfect score.

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-only tool with an output schema, the description covers the essential context: what it returns, when to use it, when not to use it, and what happens on failure. Nothing an agent needs to call it 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?

Schema description coverage is 100%, and the only parameter, roadmap_id, is already documented as 'Roadmap ID'. The description does not add additional semantic detail about the parameter, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get'), names the exact resource ('complete roadmap'), and clarifies that it combines details, bars, lanes, and milestones. It distinguishes itself from get_roadmap, so an agent can tell them apart without needing to inspect 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 'USE WHEN' section gives concrete example queries ('Full roadmap overview', 'Summarize roadmap X'), explicitly directs the agent to get_roadmap for settings/metadata only, and provides a failure fallback ('use list_roadmaps' when roadmap_id is not found). This leaves no ambiguity about when to select this tool.

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

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

Annotations already indicate readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral detail beyond annotations: it specifies the returned fields, confirms the API exposes no lane color, and documents the failure mode for an invalid roadmap_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 compact, front-loaded with the core purpose, and uses clear labeled sections ('USE WHEN', 'FAILS WHEN'). Every sentence contributes either selection guidance, return shape, or failure behavior without 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 simple read-only getter with one required parameter, 100% schema coverage, an output schema, and relevant annotations, the description covers purpose, usage conditions, returned data, and failure handling. Nothing essential is missing.

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

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

Schema coverage is 100%, so the description does not need to compensate. The description does add helpful context about roadmap_id being the identifier whose absence causes failure, but it does not add new parameter-level semantics beyond the schema's 'Roadmap ID' 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 uses a specific verb and resource ('Get lanes on a roadmap') and immediately clarifies the domain concept: 'Lanes organize bars into rows.' This clearly distinguishes it from sibling tools like get_roadmap_milestones or get_roadmap_legends.

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 includes explicit 'USE WHEN' example queries ('What lanes are on the roadmap?', 'Show categories') and a concrete failure-handling instruction with the alternative tool ('use list_roadmaps'). This gives an agent clear conditions for selection and fallback.

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

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

Annotations already declare readOnlyHint=true, and the description builds on that by revealing the API limitation: legends are name-only, with no ID or hex color. It also explains how the returned names are consumed by manage_bar and bulk tools. No contradiction with annotations; adds behavioral nuance beyond the read-only 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?

The description is structured with clear sections (USE WHEN, returns, usage, alternatives, FAILS WHEN), and every sentence contributes value. It is slightly longer than the absolute minimum, but the length is justified by the routing and usage details, and it remains front-loaded with the core purpose.

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

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

For a single-parameter read-only tool with a well-documented schema and output schema, the description covers everything an agent needs: purpose, usage cues, alternative tools, failure handling, and how to apply the results. Nothing essential is missing.

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

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

There is only one parameter, roadmap_id, and the schema description 'Roadmap ID' fully covers its meaning. The tool description adds no extra semantics for this parameter, but with 100% schema coverage, the baseline of 3 is appropriate and no further clarification is needed.

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 returns legend names (bar colors) for a roadmap, specifying the exact resource and action. It also explicitly distinguishes itself from get_roadmap (custom field definitions) and get_roadmap_bars (finding bars by legend), making it unambiguous among 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?

The description includes a dedicated 'USE WHEN' section with concrete example queries, and a 'FAILS WHEN' section with fallback guidance (use list_roadmaps). It also names two alternative tools and the conditions for choosing them, giving agents explicit routing 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, so the description doesn't need to restate that. It adds value by disclosing the return shape (array of milestones with ID, title, date) and the failure condition when the roadmap_id is invalid. This goes beyond the annotations and helps an agent anticipate outcomes.

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 concise segments: purpose, when to use, and failure handling. Everything is front-loaded and directly actionable, with no filler or redundant phrasing.

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, read-only tool with an output schema, the description covers the essential context: what it returns, when to use it, when it fails, and how to recover. No significant gaps remain.

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

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

The schema only says 'Roadmap ID', which is minimal. The description adds that the ID must correspond to an existing roadmap (otherwise it fails) and suggests using list_roadmaps to discover valid IDs. This gives practical meaning beyond the bare parameter label.

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

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

The description clearly states the tool retrieves milestones (key dates) on a roadmap, which is a specific verb and resource. It is distinct from siblings like get_roadmap and get_roadmap_bars because it focuses on milestones only, and there is no other get_milestone 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?

Explicit 'USE WHEN' conditions ('What are the key dates?', 'Show milestones') guide when to invoke this tool. The 'FAILS WHEN' section names the failure mode (roadmap_id not found) and directs to list_roadmaps as an alternative for finding a valid ID.

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

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

Annotations declare readOnlyHint=true, and the description adds failure conditions (FAILS WHEN deep=true and API is unreachable) and clarifies that basic health always succeeds when the server runs. This provides behavioral context beyond annotations, though it does not detail the return format (mitigated by an output schema being 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?

The description is compact and uses labeled sections (USE WHEN, FAILS WHEN) to structure information efficiently. It is slightly longer than the minimal two-sentence example but every sentence adds value and is well front-loaded with the core purpose.

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

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

Given the tool's simplicity (one optional parameter), the presence of an output schema, and annotations covering read-only behavior, the description is complete. It covers when to use, when not to use, failure modes, and the difference from the sibling tool, leaving nothing critical unexplained.

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 describes the deep parameter at 100% coverage, but the description adds the failure condition tied to deep=true, which enriches the parameter's semantics. This goes beyond the schema's 'Also verify API connectivity (~500ms)' by specifying the consequence of that verification.

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 'Check' and the resource 'MCP server health and cache stats', making the tool's purpose unmistakable. It also explicitly differentiates from the sibling check_status by noting that check_status is for API connectivity only, so an agent can distinguish between 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 explicit USE WHEN scenarios ('Server status', 'Rate limits', 'Diagnose issues') and gives a direct alternative ('For API connectivity only, use check_status instead'). This leaves no ambiguity about when to select this tool over its sibling.

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 it read-only, and the description adds useful behavioral context: it returns customer names and linked idea counts, and it fails when the API token is invalid. This goes beyond the annotation-provided safety profile without contradicting it.

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

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

The description is concise and front-loaded with purpose, then uses compact USE WHEN / FAILS WHEN lines for additional guidance. Every sentence contributes value with no redundancy.

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

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

For a zero-parameter, read-only list operation with an output schema, the description covers purpose, usage context, return content, and a failure condition. Nothing needed 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?

The tool has zero parameters, so the description has no parameter documentation burden. Baseline 4 is appropriate since there is nothing for the schema or description to clarify.

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

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

States a specific verb and resource ('List all customers') plus the scope ('across ideas') and what is returned. This clearly differentiates it from sibling list tools like list_users and list_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?

Provides explicit USE WHEN cues ('Who are our customers?', 'All feedback sources') that help an agent decide when to select it. It does not name specific alternatives or exclusion conditions, but the context is clear enough that this is not a gap.

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 the description adds useful behavior beyond that: it aggregates tags across all ideas, returns usage counts, and explicitly states a failure condition for invalid API tokens. This is meaningful operational context beyond the annotation fields.

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

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

The description is compact and front-loaded with the core action, then supplemented by clearly labeled USE WHEN and FAILS WHEN sections. Every line carries useful information without unnecessary elaboration.

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

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

For a zero-parameter read-only listing tool with an existing output schema and annotations, the description covers operation, scope, return semantics, and a failure mode. Nothing essential is missing for an agent to select and invoke this 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?

The tool has zero parameters and the input schema is empty, so there is no parameter behavior to explain. The baseline of 4 applies because the description cannot and need not add parameter-level detail.

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 ('List all tags') and further scopes it to tags 'used across ideas' with usage counts. This clearly distinguishes it from sibling list/get tools that operate on ideas, customers, launches, or roadmaps.

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 WHEN section gives concrete user-intent triggers like 'What tags exist?' and 'Show categories', making it easy to know when to invoke this tool. It does not explicitly name alternatives or when-not-to-use cases, but no sibling tool covers tags, so the guidance is sufficiently clear.

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

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

Annotations declare readOnlyHint=true, and the description adds return format (array with ID and name) and a failure condition (invalid API token). This goes beyond annotations, though it doesn't disclose other traits like pagination or ordering, which are likely unnecessary for a simple list.

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 lines: main action, when to use, failure condition. No fluff, and the primary action is front-loaded. Every sentence serves a purpose.

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

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

For a parameterless list tool with an output schema and read-only annotation, the description covers the essential usage triggers and failure mode. Nothing critical is missing for an agent to decide and call 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 tool has zero parameters, so the description correctly omits parameter details. With schema coverage at 100% (no params), the baseline of 4 applies and the description adds no unnecessary param info.

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

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

The description clearly states 'List idea submission forms' with a specific verb and resource. It also specifies the return type (array with ID and name) and is easily distinguishable from siblings like get_idea_form (singular) and list_ideas (different resource).

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

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

It provides explicit USE WHEN examples ('Show feedback forms', 'What forms exist?') that trigger this tool, giving clear context. It doesn't explicitly exclude alternatives, but sibling tools are distinct resources, so the intended usage is unambiguous.

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 read-only, and description adds failure modes (invalid token, invalid sort field), empty-list behavior, and server-side filtering semantics. This goes well beyond the structured 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 compact, uses labeled sections, and front-loads the entry-point guidance. No wasted words.

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

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

With 3 optional well-documented params, an output schema, and read-only annotations, the description covers return fields, filter semantics, and failure conditions. Nothing essential is missing for correct invocation.

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

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

Schema covers 100% of parameters, but the description adds practical semantics: case-insensitive name matching, exact channel matching, and a sort example. It clarifies the optionality and server-side execution.

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

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

Description opens with 'List all ideas in discovery pipeline,' a specific verb-resource pair that identifies this as the collection retrieval tool. The 'START HERE' marker and 'List all' clearly distinguish it from singular get_idea and mutating manage_idea 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 explicit 'USE WHEN' examples ('Show customer feedback', 'What ideas do we have?') that tell an agent when to invoke it. It doesn't explicitly name alternatives or when-not-to-use, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false. The description adds the failure mode (objective_id not found) and the return structure, which are useful behavioral details beyond annotations. No contradiction; the description does not claim mutation or idempotency.

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

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

The description is extremely concise, with a clear purpose statement followed by labeled sections (USE WHEN, Returns, FAILS WHEN). Every sentence earns its place, and the most critical information (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?

Given the output schema exists (and the description already lists the return fields), plus annotations covering read-only behavior, the description is nearly complete. The only minor gap is the lack of explicit pagination or ordering details, but for a per-objective key result list, that is likely acceptable and the failure condition is well handled.

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% (objective_id is described as 'Objective ID'), so the baseline is 3. The description's reference to 'for an objective' and the failure condition slightly clarifies the parameter's role, but does not add syntax or format details beyond what the schema already provides.

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

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

The description states a specific verb ('List') and resource ('key results') with a clear scope ('for an objective'). It distinguishes from sibling tools like 'get_key_result' (singular) and 'list_objectives' (different resource), and explicitly mentions the return fields (ID, name, target_value, current_value).

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

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

Provides explicit 'USE WHEN' conditions ('What are the KRs?', 'Show metrics') and a 'FAILS WHEN' clause that names the condition (objective_id not found) and the alternative tool (list_objectives). This gives clear routing guidance beyond 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, so the read-only nature is covered. The description adds valuable failure conditions (invalid token, date format, sort field) and explicitly states the empty-list behavior. This goes beyond the annotations by clarifying error handling and return expectations. It doesn't cover rate limits or pagination, but that's minor given the tool's simplicity.

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

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

The description is well-structured and front-loaded: it opens with the core purpose, then usage triggers, then filter details, then return shape, then failure cases. Every sentence serves a distinct function, and there is no redundant or filler content. The formatting (caps, line breaks) aids readability. This is a model of concise, complete documentation.

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

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

Given the tool's simplicity (5 optional params, no nested objects) and the presence of an output schema, the description covers all necessary aspects: purpose, filters, return fields, and failure modes. It doesn't mention pagination or result limits, which could be relevant for a 'list all' operation, but this is not explicitly required and may not apply. The description 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?

The schema provides 100% coverage with descriptions for all five parameters. The description summarizes filters (name_contains, status, dates, sort) but doesn't add information beyond what the schema already specifies. The mention of 'inclusive' for dates mirrors the schema's 'on or after' phrasing. Thus, the description adds no net semantic value over the schema, aligning with the baseline 3 for high coverage.

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

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

The description clearly states 'List all launches' with a specific verb and resource. It adds 'START HERE for launches' to indicate it's the primary entry point, distinguishing it from get_launch (singular) and manage_launch (modification). This is a strong purpose statement with clear sibling differentiation.

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

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

The description provides explicit USE WHEN examples ('Show launches', 'Release schedule', 'Launches this quarter') and marks it as the starting point. It doesn't explicitly state when not to use it or name alternatives, but the context and sibling names make it clear that get_launch is for single records and manage_launch for writes. The guidance is strong but could be enhanced with explicit exclusions.

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

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

Annotations already mark the tool as read-only, and the description goes further by disclosing the return shape (fields included), the empty-list behavior, and the specific failure mode for invalid API tokens. This adds meaningful behavioral context beyond the structured annotations with no contradictions.

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 tightly organized into labeled sections: purpose, use-when, return shape, and failure mode. Every sentence contributes a distinct fact, with 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 zero-parameter list tool, the description covers the essential agent-facing context: what is returned, when it fails, and what happens when there are no objectives. The presence of an output schema covers the detailed return structure, so nothing important is missing.

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

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

The tool takes zero parameters and schema description coverage is 100%, so there are no parameter semantics left unexplained. Per the baseline for zero-parameter tools, this is appropriately handled.

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 'List all OKR objectives' — a specific verb plus resource with explicit scope. The 'START HERE for OKRs' marker and inclusion of key_results_count signal that this is the collection-level entry point, clearly distinguishing it from siblings like get_objective and manage_objective.

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 WHEN' section provides concrete user intents ('Show OKRs', 'What are our objectives?') that map directly to agent invocations. It does not explicitly list when-not-to-use or name alternatives like get_objective, but 'START HERE' and the sibling list imply the boundary sufficiently.

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

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

Annotations already declare readOnlyHint=true, and the description adds value by detailing return contents (array with ID, problem_statement, workflow_status, linked idea count), empty-list behavior, and two specific failure modes (invalid token, sort field outside allowed list). This goes beyond the annotation's binary safety signal, though it doesn't mention rate limits or pagination.

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

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

The description is compact and well-organized into labeled sections (USE WHEN, filters, returns, FAILS WHEN). It front-loads the core purpose and avoids redundancy, though the 'USE WHEN' examples and filter details could be trimmed slightly 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 read-only list tool with three optional parameters and an output schema, the description covers the essential call context: what is returned, when it fails, and how filters behave. It does not mention pagination or result limits, but these are not critical for a list endpoint of this simplicity, and the output schema fills remaining 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?

The input schema has 100% description coverage, so the schema already documents each parameter's meaning and constraints. The description merely restates the filter semantics (case-insensitive, exact match) and gives one sort example, adding marginal value. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the resource ('opportunities') and the verb ('List'), making the purpose unambiguous. It also adds a 'START HERE for discovery' hint that signals its role as an entry point, but it does not explicitly name any sibling tool (e.g., get_opportunity) to differentiate, so it misses the top score.

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 concrete USE WHEN examples ('Show opportunities', 'Discovery pipeline') and explains failure conditions (invalid token, invalid sort field). It does not explicitly exclude alternative tools or mention when to prefer a sibling, but the triggers are clear enough for an agent to decide.

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 significant behavioral context beyond the annotations: it specifies the return fields (ID, name, updated_at), the exact failure conditions (invalid/expired API token, sort field outside allowed list), and that filters are server-side. The annotations only declare readOnlyHint=true, which is not contradicted; the description enriches the agent's understanding of edge cases.

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

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

The description is well-structured with clear sections: purpose, use-when, filters, returns, and fails-when. It is front-loaded with the primary purpose and uses line breaks for readability. Every sentence contributes actionable information with zero fluff.

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

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

For a list tool with two optional parameters and an output schema present, the description covers all essential aspects: use cases, filter semantics, return fields, and failure modes. The agent has everything needed to decide when to call it and what to expect, including how to handle errors.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by noting that name_contains is case-insensitive and providing example values for sort ('name asc', 'updated_at desc'). These details clarify usage beyond the schema's formal definitions, earning a 4.

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

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

The description opens with 'List all roadmaps' and 'START HERE to get roadmap IDs', which is a specific verb+resource that clearly distinguishes this tool from get_roadmap (which fetches a single roadmap). It also states the primary use case for obtaining IDs, making its purpose unmistakable.

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 explicitly lists trigger phrases ('Show my roadmaps', 'What roadmaps do I have?', 'Find the Mobile roadmap') and describes optional filters. However, it does not explicitly state when to use an alternative (e.g., get_roadmap for a specific roadmap), though 'START HERE' implies it is the entry point. Slight gap in naming alternatives, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered structurally. The description adds the account-level scope, which is useful, but does not disclose additional behavioral details such as pagination, ordering, or response size. The description does not contradict 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, well-structured, and front-loads the core purpose before the usage guidance. Every sentence earns its place with no redundant content.

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

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

Given zero parameters, a read-only annotation, an output schema, and a clear distinction from list_users, the description fully equips an agent to select and invoke this tool correctly. Nothing critical is missing.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because parameter documentation is unnecessary here.

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

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

The description states a specific verb and resource ('List all teams in account') with a clear scope, and explicitly distinguishes itself from list_users. An agent can immediately understand what this tool does and how it differs from the sibling for individual user details.

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

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

Provides concrete USE WHEN triggers ('What teams exist?', 'Team structure') and explicitly names the alternative tool (list_users) for individual user details. This gives clear routing guidance with no 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 declare readOnlyHint=true, so the safety profile is covered. The description adds that it returns an array with ID, name, email, and role, which is useful but partially redundant with the output schema. It does not disclose pagination, ordering, or authentication requirements, but for a simple read-only list with annotations, this is adequate.

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

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

The description is compact and front-loaded with the core purpose, followed by a practical usage trigger and return-format note. Every sentence adds value, and there is no fluff 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 parameterless read-only list tool with an output schema and annotations, the description is complete. It states the scope, return fields, and a direct integration use case with manage_launch_task, leaving no critical gaps for an agent to call it correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The schema coverage is 100% and the description correctly implies no inputs are needed. Baseline 4 is appropriate for a parameterless tool.

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

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

The description states a specific verb and resource: 'List all users in account.' It clearly identifies the scope (account-wide) and distinguishes this from sibling tools like list_teams and list_all_customers by focusing on users.

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

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

The 'USE WHEN' section provides concrete trigger phrases ('Who has access?', 'Team members') and explicitly connects this tool to manage_launch_task by telling agents to use its user IDs for assignment. It lacks explicit when-not-to-use or alternative tool names, but the context is clear.

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

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

Annotations only declare destructiveHint=true, but the description goes far beyond that: it discloses omitted fields are never sent, new bars are parked by default, names are canonicalized case-insensitively, legend_id is rejected to prevent color wiping, bars cannot be un-nested, and delete is permanent. This is substantial behavioral context that directly informs how the agent invokes the tool.

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

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

The description is dense but well-structured with USE WHEN, Actions, and FAILS WHEN sections. Every section adds operational value, and front-loading the core action makes the tool's purpose immediately clear despite the large parameter surface.

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 24-parameter mutation tool with no output schema, the description covers invocation intents, alternative routing, failure conditions, return values for create/update, default behaviors, naming rules, deprecation traps, and permanence of deletion. This is as complete as an agent needs for correct selection and invocation.

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

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

Although schema coverage is 100%, the description adds critical semantic constraints not derivable from the schema alone: legend names must come from get_roadmap_legends, nested bars must match the container's parked state, container_bar_id requires both dates and cannot be removed, and effort/legend_id are rejected. This meaningfully improves parameter understanding.

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

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

The description opens with a specific verb and resource: 'Create, update, or delete a bar on a roadmap.' It also differentiates itself from bulk siblings by explicitly naming single-bar actions and pointing to bulk_create_bars, bulk_update_bars, and bulk_delete_bars for multi-bar scenarios.

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 WHEN' section lists concrete user intents like 'Add feature', 'Update dates', and 'Delete item', and explicitly directs agents to bulk_* tools when handling many bars at once. The 'FAILS WHEN' section further clarifies invalid usage conditions, leaving little ambiguity about when this tool is appropriate.

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

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

Annotations already mark this as destructive and non-idempotent. The description adds valuable behavioral detail beyond that: it specifies exactly which parameters cause failures and directs the agent to get IDs from get_bar_connections. This helps the agent anticipate failure modes 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 compact and front-loaded with the core purpose, followed by use cases, actions, and failure conditions. Every sentence carries useful information, and the structure makes it easy for an agent to parse quickly.

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 essential context: what it does, when to use it, which parameters are needed per action, and where to obtain IDs. It does not describe return values, but that is less critical for a create/delete operation and no output schema is present.

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 meaningful parameter semantics by mapping action values to their required parameters (create → target_bar_id, delete → connection_id) and explaining the failure conditions. This goes beyond the schema's individual field descriptions.

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

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

The description opens with a specific verb and resource: 'Create or delete dependency between bars.' This clearly identifies the tool's function and distinguishes it from read-only siblings like get_bar_connections. The action list further clarifies the two modes of operation.

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 WHEN' section explicitly lists triggering intents ('Link features', 'Add dependency', 'Remove dependency'), and 'FAILS WHEN' gives concrete error conditions. It does not explicitly name alternatives or exclusion cases, but the guidance is clear enough for an agent to select this tool 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 carry destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the low-level safety profile is covered. The description adds genuine value beyond that: explicit failure conditions per action, the requirement to fetch IDs from get_bar_links, and the API limitation that update is unsupported. It aligns with, and does not contradict, the annotations.

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

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

The description is compact and front-loaded with the core purpose, then organized into labeled blocks (USE WHEN, Actions, FAILS WHEN, Note). Each sentence earns its place, though the Actions line partially restates what the input schema already enumerates. No redundancy or padding beyond that.

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 5-parameter mutation tool with no output schema, the description covers purpose, when to use, failure modes, where to source IDs, and the update workaround. The only gap is a statement of expected return/success behavior, which is minor given the annotations already flag this tool as destructive and non-idempotent.

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 an action-to-parameter contract that the schema lacks: create requires url, delete requires link_id. This conditional relationship between the action enum and other parameters meaningfully exceeds the flat per-field schema descriptions.

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

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

The first sentence states a specific action pair and resource: 'Create or delete external link on a bar.' The USE WHEN examples ('Link Jira ticket', 'Add design doc', 'Remove link') ground it in concrete user intents. It is clearly distinguished from siblings like get_bar_links (read-only) and manage_bar_connection (connections, not links).

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 USE WHEN block with example intents, and direct FAILS WHEN conditions for each action. It names the alternative tool (get_bar_links) for sourcing link_id and gives an explicit exclusion: update is not available via API, so delete-and-recreate is the prescribed path. Nothing is 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?

The description adds several behavioral facts not visible in annotations: create requires title, update requires idea_id, the operation returns the created/updated idea object, and delete is unsupported. It also gives the failure conditions and the archival workaround. The destructiveHint=true annotation is not contradicted; it is consistent with updates potentially overwriting existing data, and the description actually narrows that destructiveness by ruling out deletion.

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 organized with labeled sections (USE WHEN, Actions, Returns, FAILS WHEN) and front-loads the core purpose in the first sentence. The only flaw is that the 'delete not available' note appears twice, adding minor redundancy without new 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 moderate parameter count, two enums, and no output schema, the description covers what is needed to invoke correctly: the action-dependent requirements, return object, and failure modes. It does not detail the structure of the returned idea object, but the high-level 'idea object' plus existing schema descriptions is sufficient for selection and invocation.

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

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

The schema already describes all five parameters (100% coverage), so the baseline is 3. The description adds action-dependent semantics by stating that create uses title and update uses idea_id, and by naming the failure conditions for missing those fields. This clarifies how to combine the action enum with the other parameters beyond the schema's property-level descriptions.

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

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

The description opens with a specific verb-plus-resource statement, 'Create or update an idea,' and goes on to enumerate the exact actions and their required fields, making the tool's role unmistakable. The explicit 'delete not available via API' sets the perimeter and helps distinguish it from other manage_* siblings. 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?

It provides explicit use triggers via 'USE WHEN: "Add idea", "Update idea status"' which map to common agent intents. It also states when not to use it (delete) and the alternative 'archive ideas by updating status instead'. This is explicit enough to route an agent to the correct tool.

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

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

Annotations already flag destructiveHint=true, and the description adds concrete behavior: what actions exist, what each returns, and the conditions under which calls fail. It does not over-explain, but it goes beyond the annotation by describing return behavior and required preconditions per action.

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

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

The description is compact and scannable, using labeled sections (USE WHEN, Actions, Returns, FAILS WHEN) that front-load the most important operational info. Every line carries information; there is 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 6-parameter CRUD tool with no output schema, the description covers action selection, required arguments, return values, and failure modes. It is complete enough for an agent to call the tool correctly without additional documentation.

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?

Although the schema has 100% parameter coverage, the description adds action-specific meaning the schema does not: create requires name+target_value, update/delete require key_result_id, and omitting these causes failure. This materially reduces ambiguity around which parameters matter for which action.

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, update, or delete a key result,' a clear verb-resource pair that defines the tool's CRUD scope. It distinguishes itself from read-only siblings like get_key_result and list_key_results by explicitly naming its write actions.

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

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

It provides explicit 'USE WHEN' triggers ('Add KR', 'Update progress', 'Delete KR') and a 'FAILS WHEN' section that routes the agent to list_key_results when an ID is missing. This gives both inclusion and exclusion criteria with an alternative.

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 destructive behavior, but the description adds valuable specifics: deletion removes the lane and unassigns all bars in it, update requires a lane_id, and color is rejected. It also states what the tool returns per action, which is especially useful since there is 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?

The description is well-structured with clear sections: summary, USE WHEN, Actions, Returns, FAILS WHEN, and WARNING. Every section adds operational value, and there is no filler or repetition beyond what is necessary.

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 7-parameter CRUD tool with three action modes and no output schema, the description is operationally complete. It covers when to use it, per-action parameter requirements, return behavior, failure conditions, and the destructive consequence of deletion.

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 each parameter. The description adds meaningful conditional semantics beyond that: create requires name, update requires lane_id plus any mutable fields, delete requires lane_id, and color is always invalid.

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 phrase, 'Create, update, or delete a lane on a roadmap,' which names both the action set and the exact resource. This clearly differentiates it from sibling tools like manage_bar or manage_milestone.

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 WHEN' section provides concrete natural-language triggers such as 'Add Backend lane' and 'Delete lane,' making it easy for an agent to know when to select this tool. It also points to get_roadmap_lanes for obtaining IDs, though it does not explicitly discuss when-not-to-use or all 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?

Beyond the destructiveHint annotation, the description explicitly warns that delete removes the launch and all its sections and tasks, and lists exact failure conditions such as missing launch_id or invalid date format. This adds meaningful 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 well-structured with labeled sections: USE WHEN, Actions, Returns, FAILS WHEN, and WARNING. It is front-loaded with the core action and every sentence carries useful information without 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 mutating tool with no output schema, the description covers actions, required parameters, return behavior, failure conditions, and the destructive consequence of deletion. An agent has enough context to call the tool correctly and understand the impact.

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 all parameters with descriptions, so the bar is higher. The description adds value by mapping actions to required parameters: create needs name+date, update/delete need launch_id. This clarifies parameter relationships beyond the schema's individual property descriptions.

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

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

The description opens with a specific verb and resource: 'Create, update, or delete a launch.' It distinguishes itself from sibling tools like get_launch and manage_launch_section by making the object of the 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 WHEN' section provides concrete trigger phrases like 'Create launch', 'Update date', and 'Delete launch', which gives clear context for when to invoke the tool. It does not explicitly name alternatives or exclusions, 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 flag destructive intent, but the description adds crucial specifics: delete removes the section and all tasks in it, and invalid action/parameter combos fail. It also describes return behavior. This is genuinely valuable beyond the structured 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?

Extremely compact and well-structured: core description, use-when examples, action mapping, return behavior, failure conditions, and warning. No fluff, and critical 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?

Covers usage, failure modes, destructive consequences, and returns, making it largely complete. The only minor gap is ambiguity about whether an 'update' action requires a name parameter to rename the section, though the examples imply 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 100%, and the description adds important action-to-parameter mappings (create uses name; update/delete use section_id) and the source for IDs. This exceeds the baseline but not overwhelmingly so, as the schema already documents each parameter.

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