AIOProductOS MCP

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

Annotations provide readOnlyHint=false and destructiveHint=false, and the description reinforces this with 'A write.' It adds valuable behavioral context beyond annotations: notes are teammates-only and never sent to the end-user, and the tool returns a result. This goes beyond what the structured fields convey.

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

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

Three sentences total: the first covers purpose and visibility, the second states the write nature, and the third gives usage guidance and the alternative. Each sentence adds unique 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 simple tool with two required parameters and no output schema, the description is self-sufficient. It covers the what, visibility, write nature, when to use, parameter resolution, and when not to use, giving an agent all necessary context 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 coverage is 100% with clear descriptions for both parameters. The description adds value by instructing to resolve conversation_id via list_conversations, which is not present in the schema, thereby providing practical guidance for parameter values.

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

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

The description clearly states 'Add an INTERNAL note to a support conversation' with a specific verb and resource. It distinguishes itself from siblings by emphasizing 'visible only to your team, never sent to the end-user' and directly naming reply_to_conversation as the alternative for public replies.

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

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

Explicitly states when to use: 'Use it to record context or hand off' and provides a cross-tool reference to resolve conversation_id via list_conversations. It also gives an exclusion: 'For a public reply use reply_to_conversation instead.'

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. Beyond that, the description discloses important behavioral traits: evaluation order ('evaluated in the exact order you pass'), dependency on event flow, and failure mode ('returns empty counts when none match'). It also explains the no-steps behavior as a menu of event names, adding context not present in 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 three sentences long, front-loaded with the core purpose, and every sentence adds distinct value: what it computes, prerequisites/failure mode, parameter usage, and sibling relation. No filler or redundancy.

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

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

The description covers the tool's purpose, prerequisites, failure mode, parameter usage, and relationship to sibling tools. With an output schema present, return values need not be described. For a 3-parameter tool with all optional parameters and no required params, this description is complete and robustly contextual.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches this by clarifying that `steps` is an ordered list of 2+ event names and advising to call with no steps to get available events. It also adds a maximum for window_days ('valid 1–365') not present in the schema. These additions go beyond the schema's 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 clearly states the tool's function: 'Build a conversion funnel from the product's own events: distinct users per step, step-to-step conversion %, and drop-off, evaluated in the exact order you pass.' It uses a specific verb ('build') and resource ('conversion funnel'), and explicitly distinguishes from sibling tools by naming analyze_paths as a complement for where drop-offs go.

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: 'Needs product-analytics events flowing; returns empty counts when none match' sets a prerequisite, and 'call it with NO steps first to get the menu of available event names rather than guessing them' gives a concrete workflow. It also names an alternative/complementary tool: 'Pairs with analyze_paths to see where the drop-offs go,' which fulfills the when-to-use vs. alternatives criterion.

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 idempotent behavior. The description adds valuable behavioral specifics: deterministic computation from survey responses, handling of window_days with default and valid range, and empty result when no responses fall in the window. It also surfaces the business scenario of unhappy high-MRR customers, which goes beyond 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?

Four dense sentences convey outputs, business value, computation behavior, edge cases, and workflow without filler. Every sentence adds distinct information, and the structure front-loads the primary 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 absence of an output schema, the description adequately explains return values (standard NPS, revenue-weighted NPS, detractor accounts). It covers computation method, parameter behavior, edge cases, and integration with adjacent tools, making it complete for an analysis tool with strong annotations.

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

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

Schema already covers both parameters with descriptions, but the description adds a maximum constraint for window_days (365) that is absent from the schema. It also clarifies how window_days influences computation and restates product_id optionality. This is meaningful supplemental information beyond schema.

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

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

The description clearly states the tool computes standard NPS, revenue-weighted NPS, and detractor accounts ranked by MRR-at-risk. This specific verb+resource combination distinguishes it from sibling analysis tools like analyze_funnel and analyze_nrr.

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 workflow guidance: quantify sentiment after get_product_brain, then dig into a detractor with get_customer_360. This gives context on when to use the tool in sequence, though it doesn't state explicit 'when-not' conditions or alternatives for exclusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds substantive behavioral detail: it is 'computed deterministically off subscription movements inside window_days', includes the default and valid range (90, 1–365), and the edge case of being 'empty when none fall in the window'. This goes well beyond annotation information.

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

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

Three sentences, each with a distinct role: enumerate outputs, explain the key interpretative insight, and specify computation/usage. The description is front-loaded with the most important information and contains 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 tool with no output schema, the description adequately specifies what the return contains (NRR, logo retention, split, ranked losing accounts), the computation basis, and the edge case. It also provides a workflow suggestion, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage for window_days is 100% with type, default, minimum, and description. The tool description adds 'valid 1–365', a maximum not present in the schema, and explains its role in the computation. This is a useful addition but the schema already carries most of the parameter meaning, so a baseline of 3 is appropriate.

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

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

The description explicitly identifies the tool's function: computing Net Revenue Retention (revenue-weighted) alongside logo retention (count-weighted), including the expansion/contraction/churn split and the top-losing accounts by MRR. It clearly distinguishes itself from sibling retention tools by focusing on the divergence between logo and revenue retention, and even points to get_customer_360 as a follow-up.

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

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

The description provides a clear context: 'Quantify revenue health, then follow the top-losing accounts into get_customer_360.' This gives an explicit use case and workflow. However, it does not explicitly state when not to use this tool or how it compares to alternative retention metrics like get_retention, so it lacks full exclusion 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond this: 'Returns the next-step transitions ranked by user count (most common first), empty when no events match' and notes it uses 'the product's own events.' This explains the output behavior and edge case, but does not describe pagination or detailed return structure.

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 yet information-dense, with a clear front-loaded purpose statement followed by return behavior, usage guidance, and parameter semantics. Every sentence adds value; there is no filler or redundancy.

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

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

Given no output schema, the description adequately covers return behavior (ranked transitions, empty case), parameter semantics, and provides a pointer to a sibling tool for event name discovery. It is complete for the tool's complexity and context.

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

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

Schema coverage is 100%, with each parameter already described. The description enriches this by stating that `start` anchors the flow, omitting it uses the most common start, `product_id` comes from whoami, and `window_days` has a default of 30 and valid range 1–365. These details go beyond the schema.

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

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

The description clearly states the tool's function: 'Trace what users do AFTER a start event — the journey flow (Sankey) from the product's own events.' It specifies the resource (user path flow) and distinguishes it from the sibling analyze_funnel by focusing on next-step transitions and referencing a specific alternative for listing event names.

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 guidance on when to use this tool and an alternative: 'Pass `start` to anchor on an event, or omit for the most common start (call analyze_funnel with no steps to list the event names).' It also clarifies optional parameters and defaults, making it clear how to invoke it.

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=false, and the description reinforces this with 'A write.' It adds useful behavioral detail that the invitee is notified per scheduling settings and that a result is returned. No contradiction with annotations, though it does not mention irreversibility or permission requirements.

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

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

The description is four sentences, each earning its place: core action plus side effect, explicit write flag, prerequisite, and alternative tool. It is front-loaded with the primary purpose and contains 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 simple 1-parameter tool with no output schema and good annotations, the description fully covers the action, prerequisite, side effect, and alternative. It provides enough guidance for an agent to select and invoke cancel_booking correctly.

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

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

Schema coverage is 100% with a clear description for booking_id. The description adds a semantic constraint: 'never guess it', and reinforces that the ID must come from list_bookings, which helps the agent avoid misinformation beyond what the schema provides.

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

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

The description uses a specific verb 'Cancel' with a clear resource 'scheduled booking (call/meeting)' and states that it returns the result. It explicitly distinguishes from sibling by referencing reschedule_booking, making the tool's purpose unambiguous.

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

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

Clearly states when to use the alternative: 'To move it instead of cancelling, use reschedule_booking.' It also provides a prerequisite: 'Resolve booking_id via list_bookings first; never guess it.' This gives explicit context for when cancel_booking should be invoked.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description discloses a real webhook side-effect and warns about capturing only genuine signal. It also explicitly notes the tool persists to 'the spine' and returns the created insight, which are non-obvious behaviors that annotations do not convey.

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

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

Four sentences front-load the purpose, then cover side-effects, parameter guidance, and required fields. No wasted words; each sentence adds essential context. The structure flows logically from what → caution → how → constraint.

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 creation tool with no output schema, the description covers the action, side-effects, parameter sources, required field, and return value ('return the created insight'). It addresses the complexity of 6 parameters by explaining how to populate them, making it complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by consolidating the resolution workflow ('Resolve account_id via get_customer_360 and feature_id via list_features') and reinforcing that body is the only required field. It also restates the meaning of 'kind' but the schema already does this; the overall contribution is a slight enhancement over the schema.

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

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

The description starts with a specific verb+resource: 'Write a piece of customer feedback to the spine...' and clarifies the result ('return the created insight'). It distinguishes from read-only sibling tools like list_insights by explicitly contrasting 'not just reading'. The name and title are fully supported.

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 clear guidance on what to capture ('only capture genuine signal') and how to resolve optional identifiers via other tools (get_customer_360, list_features). However, it does not explicitly name sibling alternatives or give when-not-to-use scenarios beyond the 'genuine signal' caution, so it stops short of a full 5.

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

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

Beyond the annotations, the description discloses that the comment is authored as the connected member, visible to the whole org, and that the tool returns the created comment. It also emphasizes work-relevance, adding context about the intended normative use. No contradictions with annotations exist.

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

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

The description is three sentences, front-loaded with the action, then usage context, then a prerequisite. Every sentence contributes information without redundancy, making it concise and well-structured.

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 write tool with no output schema, the description is complete: it states the action, return value, visibility, and usage context. The annotation set covers safety, and no additional behavioral details are needed for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both id and body described. The description reinforces that both are required and adds the prerequisite to resolve the id via get_task or list_tasks, but this is already implied in the schema's parameter descriptions. Thus the description adds minimal semantic value beyond the schema.

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

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

The description states a specific verb and resource: 'Add a comment to a task', and clarifies it is authored as the connected member and returns the created comment. This clearly distinguishes it from sibling tools like add_note or post_to_channel, which target different resources.

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

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

The description provides clear usage context: 'Use to record progress, a decision, or a handoff' and warns that comments are visible to the whole org, so keep it work-relevant. It also gives a prerequisite to resolve the task id first with get_task or list_tasks, but does not explicitly mention when not to use or name alternatives.

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

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

Annotations provide no behavioral hints (all false), so the description carries the burden. It adds meaningful context: the default status of 'decided' and that a 'decided' status stamps the decision time, plus that link_type + link_id are verified within the organization. This goes beyond the schema and gives the agent useful behavioral expectations. It could mention idempotency or error handling, but the disclosed behaviors are valuable.

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

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

The description is two concise sentences with no fluff. It front-loads the primary purpose, then efficiently covers status behavior, linking, and required fields. Every sentence earns its place and does not repeat 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?

With five parameters, no output schema, and no annotation hints, the description does well to cover the required field, status options, linking constraints, and validation. It explains behavior not obvious from the schema (time stamping). It could be slightly more complete by stating what the return value looks like, but 'return it' implies the created decision. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already defines each parameter. The description adds extra semantics beyond the schema: the default status value, the timestamp stamping behavior for 'decided', and the requirement that link_type and link_id must be paired and are verified in-org. This enrichment elevates the score above the baseline of 3.

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 'Log a decision and return it,' which clearly specifies the verb (log) and resource (decision). It distinguishes from sibling tools like update_decision and list_decisions by emphasizing creation. The mention of statuses and optional linking further clarifies the exact scope.

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

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

The description clearly indicates when to use the tool: to create a decision. It states 'Only title is required' and outlines optional linking to features/releases/objectives, giving the user a sense of the typical invocation. However, it does not explicitly contrast with update_decision or list_decisions, though the context implies it. This warrants a 4 rather than 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 indicate non-readonly, non-idempotent, non-destructive behavior. The description adds that the tool returns the created experiment, defaults state to 'hypothesis', and clarifies the storage/read mechanism via list_experiments. This provides useful behavioral context beyond the annotations, though it does not elaborate on error cases or auth requirements.

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

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

The description is concise and front-loaded with the core purpose. It packs the essential info—purpose, return, required field, state default, and differentiation from A/B engine—into four short sentences with no fluff or verbosity.

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

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

For a create tool with no output schema, the description covers the key aspects: what it creates, return behavior, required/optional fields, state default, and where it fits in the broader tool ecosystem. It does not describe the return structure in detail or mention prerequisites like authentication, but annotations and schema fill in some gaps, making it fairly 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 each parameter already well-documented (state enum, required title, optional metric, target, hypothesis, product_id). The description only repeats the state default and required title, adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool creates a PM experiment (a Build-Measure-Learn hypothesis) and returns it. It explicitly distinguishes this from the analytics A/B engine, which sets it apart from related tools and potential confusion.

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

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

The description gives clear context: this is the PM tracker that list_experiments reads, and explicitly states it is not the analytics A/B engine. It also says only title is required, providing a key usage constraint. However, it does not name an explicit alternative tool for A/B experiments, slight gap for full when-to-use guidance.

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

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

The description discloses key behaviors: the generated key, the initial status 'active', the default product when product_id is omitted, and the return fields. It adds context beyond the annotations, which are all false/neutral. No contradiction exists.

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

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

The description is two sentences, front-loads the primary purpose, and packs essential details about defaults and workflow without wasted words.

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

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

The tool has 5 parameters and no output schema, but the description explicitly lists the return fields (id, key, name, status) and covers the required/optional behavior. It also places the tool in a workflow relative to create_task, making it contextually 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%, so the parameters are already well-documented. The description reinforces that only name is required and restates the product_id default, but adds little beyond the schema. 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 opens with a specific verb-object pair ('Create a feature on the product spine') and clarifies the resource and output. It distinguishes create_feature from sibling tools like create_idea and create_task, which target different entities.

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

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

The description gives clear context for when to use this tool ('create a feature here before linking tasks to it with create_task') and explains the optional product_id behavior for multi-product orgs. It does not explicitly state when not to use it, but the guidance is strong enough for an agent to select it 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 indicate this is a mutating operation (readOnlyHint false). The description adds value by disclosing the initial vote count and status, the return behavior, and the default product_id, which are behavioral traits beyond the structured 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 well-structured: two sentences with the core action upfront, followed by key parameter context and workflow. Every sentence adds necessary information without 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?

Given the 4 parameters and no output schema, the description covers the essential context: what the tool does, initial state, parameter defaults, and subsequent actions. It could provide more detail on the exact return structure, but 'return it' plus the initial field values is reasonably complete for a create tool.

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

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

The input schema already covers all parameters (100% coverage), but the description enriches semantics by explaining that insight_id links evidence from list_insights and that product_id defaults to the primary product. It also clarifies that only title is required, reinforcing the schema's required field.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create an idea in the backlog and return it.' It also distinguishes from siblings by specifying the initial state ('starts with 0 votes, status 'new'') and the workflow with vote_idea and promote_idea, making it unmistakably about ideas rather than other entities.

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

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

The description provides clear context on how to use the tool: linking with insight_id from list_insights, product_id defaulting to the primary product, and only title being required. It also hints at the lifecycle ('Grow it with vote_idea, then promote_idea...') but does not explicitly state when not to use it versus alternatives like create_feature.

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 are all false, so the description carries the burden. It adds valuable behavioral context: default status ('planned'), default product ('primary product'), and that only 'name' is required. It also discloses the relationship to objectives and next steps. It does not detail the return format or side effects, but the core behavior is well covered.

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

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

Four sentences, front-loaded with the definition and return behavior. Every sentence earns its place: definition, relationship to goals, defaults/required fields, and follow-up actions. No fluff or repetition of schema boilerplate.

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 create tool with 6 parameters, no output schema, and unusable annotations, the description is quite complete: it covers purpose, required fields, defaults, relationships, and next steps. The only gap is that 'return it' lacks detail about the returned object structure, but for a create operation this is often implied.

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 semantics beyond the schema by pointing to 'list_objectives' for objective_id, clarifying product_id defaults to the primary product, and giving concrete examples for timeframe ('H2 2026'). This elevates it to a 4.

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

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

The description opens with a specific verb ('Create') and resource ('initiative'), clearly defining an initiative as 'a strategic effort that groups features and rolls up to a goal.' This distinguishes it from sibling tools like create_feature or create_objective, and the phrase 'and return it' signals the expected outcome.

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

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

The description provides clear context on when to use the tool—when creating a new strategic effort—and offers integration guidance ('Link it to a goal with objective_id' and 'Then align features to it via create_feature / update_feature'). However, it does not explicitly contrast with update_initiative or state when not to use it, so it stops short of full 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 are all false, so the description carries the transparency burden. It adds valuable behavioral context by noting that product_id and parent_id must be 'verified in-org' and that the tool 'return it' (the created objective). This goes beyond the schema. It does not mention idempotency or potential duplicate creation, but 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 two sentences, front-loaded with the primary action. Every clause adds relevant detail: creation, optional key results, return value, parameter constraints, and required fields. No unnecessary words 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?

Given no output schema, the description mentions the return ('return it') but not the exact return format. It covers key usage constraints (required name, optional fields, verified in-org) and key results structure. Limitations like 'up to 10 key results' are present only in the schema, not the description. Overall, it is sufficient for an agent to use correctly, though a few details remain implicit.

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 baseline is 3. The description adds meaning by clarifying that period is free text, emphasizing optionality and in-org verification for product_id and parent_id, and explaining the key results structure (name required, unit/start_value/target_value optional). This supplements the schema descriptions effectively.

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: 'Create an objective, optionally with key results, and return it.' It uses a specific verb ('create') and resource ('objective'), and effectively distinguishes this tool from siblings like update_objective or create_initiative. The scope is unambiguous.

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

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

The description provides clear contextual clues: period is free text, product_id and parent_id are optional and 'verified in-org', which informs how to source those parameters. However, it does not explicitly mention when not to use this tool or name alternatives such as update_objective for editing existing objectives.

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

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

Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description adds meaningful behavioral context: return values, paragraph separation, default title, and in-org verification. No contradiction with annotations.

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

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

Two sentences, front-loaded with the main purpose, and every clause adds necessary detail. 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?

The description is self-sufficient for a create tool with no required parameters and no output schema. It covers defaults, body behavior, optional IDs, validation, and the shape of the return value.

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 some context beyond schema (e.g., return id/title, verified in-org), but much of it restates the schema (title defaults to 'Untitled', blank-line paragraph separation). Overall, 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 identifies the action ('Create'), the resource ('Page'), and the context ('in-product doc / PRD on the spine'). It also states what is returned (id, title), making it easy to distinguish from update_page or list_pages.

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

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

The description explains key usage details: body formatting, title default, and optional/verified product_id and parent_id. It does not explicitly contrast with update_page or list_pages, but the context is clear enough for correct use.

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?

Given that annotations are all false (no hints), the description carries the burden of disclosure. It clearly states what is returned, the optionality of released_at, and the default for product_id. This adds meaningful behavioral context beyond the schema and annotations, though it does not mention side effects like potential validation errors.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds valuable information. No filler or redundancy.

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

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

The description covers the return format, draft behavior, default behavior, and required parameter. With no output schema, this is sufficient for an agent to invoke the tool correctly and understand the basic result. It lacks error-condition details, but they are not critical for a simple create operation.

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

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

Schema description coverage is 100%, so the schema already explains each parameter. The description reiterates the semantics of released_at and product_id but does not add new information beyond the schema. 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 opens with a specific verb+resource ('Create a release') and explicitly states return fields and the only required parameter. This clearly distinguishes it from sibling tools like update_release or list_releases.

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

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

The description provides clear context on usage, including draft behavior ('Omit released_at for a draft') and defaulting behavior for product_id. It does not explicitly name alternatives or exclusions, but the context is sufficient for selecting this tool for creating a release.

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 indicate no read-only/destructive/idempotent behavior, leaving the description to explain the operation. The description discloses the return payload, default state ('future'), optional dates, and the fact that only name is required. This goes beyond annotations, though it does not mention permissions or validation error behavior.

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

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

Three concise sentences deliver purpose, key parameter behavior, and downstream usage with no redundant wording. The description is front-loaded with the main action and each sentence adds necessary information.

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

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

Completes the picture for a create tool: describes return value, optional fields, defaults, and how to integrate with create_task/update_task. No output schema exists, and the description covers the essentials. It doesn't discuss error cases or permissions, but these are less critical for a straightforward create operation with good schema annotations.

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

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

Schema covers all 5 parameters at 100%, providing baseline. The description adds value by specifying state default ('future'), date format (ISO 8601), and emphasises that only name is required. This clarifies optionality beyond the schema's 'required' field.

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

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

States a specific action, 'Create a sprint and return it', with a clear resource and output. The description distinguishes this from sibling tools like update_sprint by focusing on creation and including the returned sprint id for task scheduling, which is unique to create_sprint.

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

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

Provides clear intended use: create a sprint with required name and optional fields, then use the returned id to schedule tasks. It explains the workflow downstream, but does not explicitly contrast with update_sprint or list_sprints, so a small exclusion hint is missing.

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=false (so it's a write operation). The description adds meaningful context beyond that: it states the return value, the default behavior for list_id, and the linking/scheduling effects of feature_id/insight_id/sprint_id. This gives the agent a good behavioral model. No contradiction with annotations.

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

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

The description is exactly three sentences, each with a distinct and essential contribution: function/return, defaults/linking, and ID-resolution guidance. No filler, no repetition of schema content. Front-loaded with the primary 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?

Despite having 9 parameters and no output schema, the description covers the core action, return value, defaults, linkage behavior, and ID resolution, making it sufficient for correct invocation. It doesn't describe error cases or detailed response shape, but the absence of output schema makes 'return the created task' adequate for an agent to expect the full object.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by consolidating and emphasizing key semantic nuances: the default for list_id, the linkage semantics for feature_id/insight_id, the scheduling meaning of sprint_id, and the explicit rule to resolve via specific tools. This goes beyond the 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 description opens with a clear, specific verb and resource: 'Create a task and return the created task.' It unambiguously distinguishes itself from sibling tools like update_task and delete_task by stating the creation side effect and the returned result. No ambiguity.

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

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

The description gives explicit context for when to use this tool: when creating a task, and it provides essential prerequisites such as resolving IDs via pm_meta and list_sprints, and emphasizing 'never guess them.' It doesn't explicitly mention alternatives or when not to use it, but the context is clear enough for selection among the similar 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?

Discloses irreversibility, cascading deletion of subtasks/attachments/time entries, clearing of experiment/insight/meeting links, and the return of the deleted id. This goes far beyond the annotations' destructiveHint and idempotentHint, giving essential consequence 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?

Two dense sentences cover purpose, consequences, prerequisites, and alternatives with no fluff. The leading 'PERMANENTLY' and 'Irreversible — there is no undo' front-load the most critical risk, making every word earn its place.

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

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

For a destructive tool with no output schema, it covers return value, cascade effects, id resolution, and when to prefer a non-destructive alternative. This leaves no critical gaps for an agent deciding whether and how to invoke 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?

The schema already fully documents both parameters (id and confirm) with descriptions and the 'DELETE' enum requirement. The description reinforces the need for confirmation but adds little new parameter-level meaning beyond 'Resolve the id via list_tasks' which the schema also notes. With 100% schema coverage, 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 opens with 'PERMANENTLY delete a task and return the deleted id,' clearly stating the specific action and resource. It distinguishes itself from siblings like update_task by emphasizing irreversibility and cascading deletion.

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

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

Explicitly instructs to 'Resolve the id via list_tasks and confirm intent first' and 'prefer update_task ... when you only want it off the active board.' This provides clear when-to-use and direct alternative 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, idempotentHint, and destructiveHint. The description adds that it returns the latest generated map and is empty when none generated, which is useful behavioral context beyond the annotations. 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 succinct yet information-dense. Three sentences cover content, behavior, use case, and parameter guidance without redundancy or 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 simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, return contents, empty behavior, use case, and parameter handling. The annotations cover safety properties, making the description 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 already provides 100% coverage of the product_id parameter, including its optionality and default behavior. The description repeats this information almost verbatim, adding no additional semantic meaning beyond the schema.

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

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

The description clearly states the tool returns an auto-generated codebase brain map for a product, listing specific contents (plain-language summary, module/node/edge counts, last generated timestamp, module labels). It uses a specific verb and resource, and the detailed content distinguishes it from any sibling tools.

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

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

The description explicitly says to use it to ground 'where in the code does X live?' questions and to see how the codebase splits into modules before discussing architecture or scoping work. This is clear context for when to use it, though it does not explicitly name alternatives or exclusion cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the return content (visitor + full thread, oldest first) and the constraint to resolve the ID first, going 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 three short sentences, front-loaded with the action and result, and contains no redundant content. Every sentence contributes essential 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 single-parameter read tool with no output schema, the description covers what it returns, ordering, read-only nature, and how to obtain the required ID. Sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100% with the parameter description already stating 'from list_conversations.' The tool description echoes this but adds the emphatic 'never guess it,' providing marginal value beyond the schema.

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

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

The description clearly states the tool reads one support conversation including the visitor and full message thread, ordered oldest first. This distinguishes it from list_conversations (listing) and reply_to_conversation (writing).

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 instructs to resolve conversation_id via list_conversations and never guess it, providing a clear prerequisite and alternative. While it doesn't contrast with write tools, the read-only instruction and context make usage 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?

The description discloses key behaviors beyond annotations: it explicitly mentions read-only behavior (consistent with annotations) and adds the empty-result behavior when no match is found. It also reveals the joined data structure (money + people + voice) and the exact fields returned, providing useful behavioral context not available from annotations alone.

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

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

The description is three well-structured sentences with no fluff. It front-loads the core value proposition ('Everything about ONE customer'), lists specific data points, and ends with a practical usage tip. Every sentence contributes meaningfully.

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 lookup tool with a single parameter and strong annotations, the description is complete. It covers what data is returned, how the query resolves, empty-result behavior, and when to use it. No output schema exists, but the description explicitly lists the fields returned, compensating fully.

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

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

The schema covers the single 'query' parameter fully (100% coverage) with a descriptive explanation of accepted formats. The description repeats this information without adding new semantic details. Baseline 3 is appropriate since 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 tool's purpose: retrieving everything about ONE customer (profile, subscription, MRR, user count, feedback) resolved by multiple identifiers. It distinguishes itself from sibling tools by emphasizing its aggregate 360-degree view and note to call it before answering account-specific questions.

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: 'call it before answering anything about a specific account.' It also clarifies that it resolves by id, email, domain, or company name. It lacks explicit when-not-to-use or alternative tool references, but the context is clear given the unique nature of the tool.

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

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

Beyond the readOnlyHint annotation, the description discloses the return behavior (empty when none found), the two cluster categories with confidence levels, and the caution 'review only' for low-confidence clusters. This adds meaningful context that annotations do not convey.

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

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

The description is two sentences, front-loading the core output (clusters of users on same device) and then adding types, confidence, empty behavior, and next-step guidance. Every word contributes value.

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

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

For a no-parameter, no-output-schema tool, the description fully explains what is returned (clusters, empty case), the semantics of each cluster type, and the intended next action. Nothing important is left unclear.

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 schema coverage is effectively 100% and no parameter descriptions are needed. The baseline of 4 applies; the description adds nothing beyond that, but nothing is missing.

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 clusters of ≥2 end_users on the same device, distinguishing two types ('anon_bridge' high confidence, 'device_shared' low confidence). It also names the follow-up tool (merge_end_users), making its purpose distinct from 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?

It explicitly says to use it for finding merge targets and then act with merge_end_users, providing clear when-to-use context. It lacks an explicit when-not-to-use or named alternative, so it doesn't fully earn 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, destructiveHint, and idempotentHint, so the description's 'Read-only' is redundant. It adds context about returning full content and the need to resolve the id first, but no additional behavioral details like error handling or permissions.

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

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

The description is two short sentences that front-load the action and include a valuable caution ('never guess it'). Every word serves a purpose; 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 simple get-by-id tool with one parameter, strong annotations, and no output schema, the description adequately covers what, how, and the safe read-only nature. It could describe the return structure in more detail, but 'full content' suffices for a page document.

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

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

Schema coverage is 100%, with id already described as 'Page id, from list_pages.' The description reinforces this with 'Resolve the id first with list_pages' but adds no new syntax or format beyond what the schema provides.

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

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

The description clearly states the tool reads one Page by id and returns full content, using a specific verb and resource. It distinguishes from siblings like list_pages (which lists pages) and get_task/get_conversation by explicitly naming 'Page (doc / PRD)'.

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 instructs to resolve the id with list_pages and never guess it, providing a clear prerequisite and companion tool. It doesn't enumerate exclusions but gives direct and actionable guidance for when to use this tool.

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

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

The description discloses determinism ('returns the same operating guide as plain text every call'), explicitly confirms no side effects, and details the content (grounding, spine, prioritisation, done). This adds meaningful behavioral context beyond the annotations, which already indicate read-only and idempotent. 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 two sentences, front-loaded with the tool's purpose, and every clause adds value—covering no-args, deterministic output, content summary, and usage timing. 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 deterministic, no-argument guide, the description fully covers what the tool returns, what topics it addresses, and when to use it. There's no output schema, but the description's content summary is sufficient for an agent to understand the return value. It's a complete description for this simple tool.

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

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

Since the schema has zero parameters, the baseline is 4. The description confirms 'No arguments,' which is consistent with the schema and removes any doubt. It doesn't need to add more because there are no parameters to explain.

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 a PM operating guide, using a specific verb ('returns') and a defined resource. It distinguishes itself from sibling tools by positioning it as the foundational 'house rules' to load before using other tools, which is unique among the listed operations.

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

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

The description explicitly says 'Call it FIRST, before planning or prioritising' and explains that other tools assume these rules. This gives unambiguous when-to-use guidance, even if it doesn't name alternatives. The instruction is actionable and context-rich.

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 idempotent, and the description adds valuable behavioral detail: it returns one JSON object, empty blocks when sources aren't flowing, newest-first customer signals, time-window honoring, and single-call/no-pagination behavior. This goes well beyond the annotation safety profile.

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 a clear lead sentence, a colon-delimited list of return contents, and a final usage directive. It's slightly verbose with phrases like 'so YOU can reason about it,' but every major clause carries informational weight.

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

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

With no output schema, the description compensates by enumerating the exact JSON blocks returned and explaining empty-block behavior. It also covers parameter defaults, optionality, and how this tool relates to sibling reads, making it fully self-sufficient for selecting and invoking the tool.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds extra context: product_id is 'from whoami' and the org's primary product when omitted, and the window parameter explicitly affects the time-windowed sections. This is useful but not dramatically beyond schema.

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

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

The description clearly states this tool returns a single JSON snapshot of the org's product, listing the contained blocks (revenue, analytics, features, signals, open-work counts). It explicitly differentiates from siblings by saying 'Start here to ground, then go deeper with the dedicated list_* reads and the analytics 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 gives explicit usage guidance: use this as the grounding entry point, then go deeper with list_* and analytics tools. It also clarifies that product_id is optional and defaults to the org's primary product, and that window choices are 7/30/90 days.

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?

Discloses significant behavioral traits beyond the annotations: output ordering ('newest last'), empty-cohort behavior, default window_days mapping to 8 cohorts, and the optional product_id fallback to primary product. This gives the agent a strong mental model of the tool's runtime 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?

Four sentences, roughly 70 words, front-loaded with the core purpose. Every sentence earns its place: output shape, prerequisites, parameter behavior, and fallback logic. No fluff 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?

Despite having no output schema, the description thoroughly covers the return format (grid), ordering, empty-case behavior, and parameter defaults. The tool is simple (2 optional params), and this description fully equips an agent to invoke it correctly.

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

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

Schema already documents both parameters with 100% coverage. The description adds extra meaning for window_days by explaining the relationship to cohort count ('56 = 8 weekly cohorts') and the effect of added days. product_id description adds no new info beyond schema, but the window_days semantics justify above baseline.

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

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

Description states exactly what the tool does: computes weekly cohort retention with a specific output shape ('lower-triangular grid', one row per cohort). The verb+resource is clear and distinct from sibling analytics tools like analyze_funnel or analyze_paths.

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

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

Provides clear context for use: requires product-analytics events, and returns empty cohorts when no data. It doesn't explicitly name alternatives or exclusions, but the prerequisite and edge case are clearly communicated.

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 read-only, idempotent, and non-destructive. The description adds valuable behavioral context: 'Deterministic, no LLM cost' and 'zeroed when nothing was planned or shipped in the window.' These go beyond the structured annotations and disclose edge-case behavior.

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

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

The description is dense but each sentence earns its place: output definition, determinism/cost, parameter summary, read-only and edge-case behavior, then usage guidance. It's front-loaded with the core purpose and has no 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?

With no output schema, the description thoroughly explains return values (drift score, counts, median slip days, top slipped/unplanned ships), the empty-window behavior, and the product_id scope. Combined with strong annotations and full schema coverage, it is functionally 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?

Both parameters are fully described in the schema (window has enum and default; product_id has provenance and scope). The description only restates 'window = week | month | quarter (default quarter); optional product_id' without adding new meaning, so schema coverage is 100% and the baseline 3 applies.

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

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

The description clearly states a specific computation ('Planned vs shipped features over a window') and enumerates concrete output metrics (drift score, counts, median slip days, top lists). It distinguishes itself from siblings by referencing list_features as a follow-up tool, and the name/title align with the 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?

Explicitly says 'Use it in planning reviews to check delivery against the roadmap, then open the slipped features with list_features,' providing both a clear when-to-use and a recommended next step. This differentiates it from alternatives and gives actionable context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the 'Read-only' statement adds little. However, the description adds value by disclosing that the response includes 'full comments and assignees' and emphasizes the constraint to never guess the id, going beyond what annotations 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 two sentences, with the primary purpose first and additional guidance second. Every sentence contributes information without any redundancy or 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 simple read tool with one parameter and no output schema, the description covers the essential aspects: what it does, what it returns, how to get the id, and how to pair with other tools. It lacks explicit error handling behavior, but that is not critical for this straightforward operation.

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

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

Schema coverage is 100% and the schema description for 'id' already states 'Task id, from list_tasks.' The description repeats this advice ('Resolve the id first with list_tasks'), reinforcing it but not adding new semantic meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Get one task by id and return it with its full comments and assignees.' This uses a specific verb and resource, and the mention of comments and assignees differentiates it from list_tasks and other task-related 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?

Explicit guidance is provided: 'Resolve the id first with list_tasks — never guess it; pair with update_task or comment_on_task to act on what you read.' This tells the agent when to use the tool (after listing) and names complementary tools for follow-up actions, making alternatives 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?

The description discloses determinism ('no fabricated quotes'), the side-effect of generate=1 ('rebuilds + persists'), the default read-only behavior ('apart from that rebuild'), and the empty-result edge case. This adds valuable context beyond the annotations, which already declare readOnlyHint/idempotentHint/destructiveHint, without contradicting them.

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

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

The description is dense but every clause earns its place: contents, determinism, parameter semantics, side-effect caveat, and usage guidance. It is appropriately sized for the tool's complexity and front-loads 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 an output schema exists and only two optional parameters, the description is fully sufficient: it explains the memo contents, the rebuild side effect, empty results, and a follow-up tool. The agent has all needed information to select and invoke correctly.

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

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

The schema already covers both parameters with descriptions, so baseline is 3. The description adds behavioral meaning—'week' is for past weeks, 'generate=1' triggers a rebuild+persist rather than a simple fetch—reinforcing but not substantially extending the schema.

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

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

The description clearly identifies the tool as retrieving the Weekly Product Signal Memo and specifies its contents (clustered themes, quotes, deltas, experiments, releases). It distinguishes the tool from the sibling list_insights by framing it as the weekly summary and mentioning drill-down as a follow-up.

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 a concrete usage context: 'Open a weekly review with it, then drill into a theme with list_insights.' It also explains optional parameters for fetching past weeks or regenerating. However, it does not enumerate explicit when-not-to-use conditions or alternative tools, stopping just short of full 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?

Adds behavioral context beyond the annotations: read-only status is stated, the empty-return case is disclosed, and the fields included in each version are enumerated. This enriches the readOnlyHint and destructiveHint annotations without contradiction.

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

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

Three sentences, front-loaded with the core purpose, then details and use case. Every sentence earns its place with no redundancy.

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

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

For a simple list tool with no output schema, the description fully covers purpose, return value, empty behavior, and integration with sibling tools. No 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?

Schema coverage is 100%, so baseline is 3. The description adds value by noting the parameters are the same as those passed to review_artifact, which is a useful cross-reference not in the schema.

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

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

The description clearly states it lists version history of an artifact's AI reviews, specifying the resource (artifact reviews) and verb (list), and distinguishes it from sibling tools like review_artifact and revert_to_version by mentioning the version_id handoff.

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

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

Explicitly says when to use: to see how a review changed over time and to pick a version_id for revert_to_version. Also notes it takes the same target_id/target_type as review_artifact, providing 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?

The description adds behavioral details beyond the annotations: it states the tool returns an empty list when no bookings are scheduled, and that include='all' switches to full history. It explicitly repeats read-only, which aligns with the annotation. These details clarify the result for the agent without contradicting the structured hints.

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

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

The description is two short sentences, front-loaded with the resource and purpose. The first sentence states what is listed; the second adds behavior and parameter guidance. Every clause earns its place, with no redundant 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 simple list tool with one optional parameter, the description is complete: it defines the default scope, the empty case, and the history option. Read-only behavior is covered by both annotation and description. No output schema exists, but the return value is sufficiently described as 'the bookings'.

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

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

The input schema fully describes the sole parameter 'include' as optional with enum 'all'. The description's mention of 'Pass include="all" for full history' adds no new semantic meaning beyond the schema, though it reinforces the default scope. Since schema coverage is 100%, a baseline score of 3 is appropriate.

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

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

The description clearly states that the tool lists upcoming confirmed bookings on the org's scheduling, using a specific verb and resource. It also distinguishes the tool from siblings like cancel_booking and reschedule_booking by focusing on read-only listing. The scope is explicitly limited to upcoming confirmed bookings, with an option to view full history.

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

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

The description provides clear context: use this tool to view upcoming confirmed bookings, and pass include='all' for history. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full alternative guidance. The read-only annotation and phrasing imply it's for viewing, not modifying, but no explicit exclusions are given.

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

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

The description adds behavioral context beyond the annotations by noting the tool is 'membership-scoped' and 'returns the member's channels, empty when they belong to none.' This informs the agent about the return set's scope and the empty case. The readOnlyHint, idempotentHint, and destructiveHint annotations are consistent with the description, and the description does not contradict them.

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

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

The description is three short, purposeful sentences. It front-loads the primary purpose, then adds scope and empty-case behavior, and finally points to a related tool. Every sentence earns its place with no redundancy or 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 zero-parameter, read-only list tool with strong annotations, the description is complete. It explains what is listed, the membership scope, the empty case, and points to the sibling tool for single-channel reads. No critical information 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, and the schema coverage is 100% (empty schema). The baseline for zero parameters is 4, and the description adequately conveys that the operation relies on the connected member context, so no parameter descriptions are 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 action ('List'), the resource ('team Comms channels'), and the scope ('the connected member belongs to'). It also distinguishes itself from the sibling tool 'read_channel' by explicitly noting that this lists all channels the member belongs to, while read_channel reads a single channel.

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

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

The description provides a clear alternative: 'Call read_channel with a channel_id to read one.' It implies this tool is for listing channels the member belongs to, and for reading a specific channel, use read_channel. However, it doesn't explicitly state when not to use this tool (e.g., for listing all channels regardless of membership), but the membership-scoped note offers implicit 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 and idempotentHint=true, and the description adds meaningful context: default filtering, the empty-list behavior when the inbox is clear, and the optional product scoping. This goes beyond structured fields, providing operational expectations.

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

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

The description is three short sentences, front-loaded with the core action, and every clause carries useful information. 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 simple list tool with optional parameters and no output schema, the description covers purpose, usage, parameter semantics, and behavioral outcomes. It is fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds the crucial default status behavior not fully in the schema (open + snoozed) and reinforces the product_id scoping, enhancing semantic 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 uses a specific verb 'list' with a clear resource 'support-chat conversations' and scope 'inbox'. It distinguishes from the sibling get_conversation by noting it opens the full thread, making the listing 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 explains the default status (open + snoozed) and how to include closed with status='all'. It also names the alternative get_conversation for opening a full thread, giving clear when-to-use/alternative 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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: newest-first ordering, empty list behavior, and the optional status filter with allowed values. It also lists the return fields, which is useful without an 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?

Four concise sentences, each providing necessary information: purpose, return fields, empty behavior, filter, and follow-up action. No fluff or repetition of structured data.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers what the tool returns, how results are ordered, and how to use the result with update_decision. The annotations cover safety, making this description complete for an agent.

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

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

Schema coverage is 100% with a clear description and enum for the status parameter. The description restates the optional status filter but does not add any meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool lists the org's logged decisions with specific fields (title, rationale, status, linked items) and ordering (newest first). It distinguishes from siblings like create_decision and update_decision by its focus on listing and resolving ids.

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

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

The description provides clear context: use this to list decisions and resolve a decision id before calling update_decision. It does not explicitly state when not to use it or mention alternatives, but the pointer to update_decision is a strong use-case guide.

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

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

Annotations already declare readOnly and non-destructive, but the description adds valuable behavior beyond that: 'Read-only; empty when none match' and the return array structure including verdict/decision for concluded experiments. This exceeds the annotation baseline 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 three sentences, front-loaded with the core action, followed by return details, read-only note, and usage guidance. Every sentence earns its place with no fluff 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?

Despite lacking an output schema, the description compensates by enumerating the fields returned and the empty-state behavior. It covers the tool's purpose, usage context, and parameter hints, making it complete for a straightforward list operation.

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

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

Schema coverage is 100% with both parameters fully described in the input schema. The description mentions 'Optional product_id (from whoami) and state filter' but adds no semantic detail beyond what the schema already provides, 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 clearly states 'List product experiments' with a specific verb and resource, and differentiates from sibling tools by detailing what each experiment carries (hypothesis, metric, target, state, verdict). This distinguishes it from other list_* tools and related experiment management 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?

Explicit guidance is provided: 'Use it to see what's being tested before proposing new work, and cite a concluded verdict as evidence when you create_task or review_artifact.' This gives clear when-to-use scenarios and even connects to other tools, while the optional filters are also mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations: it says returns matching features, empty when none, and emphasizes read-only access. This provides additional behavioral clarity 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 at three sentences, front-loads the core purpose, and every clause adds value—pointing out the richer data, read-only behavior, empty result case, parameter scoping, and downstream use. 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 read-only list tool with good annotations and full schema coverage, the description covers what it returns, when it returns empty, how to scope it, and how results should be used. The absence of an output schema is mitigated because the description names the fields returned and behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for product_id by noting it comes 'from whoami' and that omitting it 'spans all products', which goes beyond the schema. The q parameter's semantics are essentially repeated, but the additional product_id context justifies a slightly higher score.

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

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

The description clearly states the tool lists the product's feature catalogue with description, status, and last-touched timestamp, which is a specific verb+resource+scope. It also distinguishes itself from the sibling pm_meta by noting it is richer and not just id+name for resolution.

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

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

Explicitly contrasts with pm_meta ('richer than pm_meta (which is just id+name for resolution)'), indicating when to use this tool versus the lighter-weight alternative. It also gives actionable guidance: use a feature id from here to link a task or insight on the spine.

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

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

Beyond annotations, the description adds meaningful behavioral details: ordering by vote count, the exact returned fields, the 'empty when none' edge case, and the optional status filter. It also reaffirms the read-only nature, which is consistent with annotations and adds context about what the tool does not do.

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 moderately sized but every sentence earns its place: purpose, return format, status filter, read-only behavior, and idea/insight distinction. It is well-structured and front-loaded with the main 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?

Despite lacking an output schema, the description fully explains the return fields, ordering, empty behavior, and filter options. Combined with the rich annotations, the agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with both status and product_id already described in the input schema. The description repeats the status enum but adds no new meaning beyond the schema, 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 uses a specific verb ('List') and resource ('the org's ideas — the native, votable idea backlog'), and clearly states the ranking by vote count. It also distinguishes ideas from insights, which differentiates it from the sibling tool list_insights.

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 differentiates ideas from insights, telling the agent when this tool is appropriate versus the related insight tool. It also instructs to resolve an idea ID here before using update_idea, vote_idea, or promote_idea, providing clear guidance on when to use this tool as a prerequisite.

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 readOnly, idempotent, and non-destructive traits. The description adds valuable behavioral context beyond annotations: returns events newest first, lists exact fields, empty when no merges have run, and highlights the revert constraint for unmerge_end_users.

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

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

Two sentences, front-loaded with the main purpose, then a compact enumeration of return fields and usage guidance. No wasted words; every clause adds 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 list tool with one optional parameter and no output schema, the description is complete. It explains the output shape, ordering, empty result behavior, and the practical context for unmerge operations.

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%; the only parameter 'limit' is fully described in the schema with default and max. The description does not add parameter-specific semantics, but the schema carries the burden, 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 opens with a specific verb and resource: 'List the org's end-user merge history.' It clearly distinguishes this list tool from the sibling merge/unmerge mutation tools by emphasizing it returns history and is read-only.

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

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

Explicitly states when to use it: 'Use it to audit identity changes and to find the event id to pass to unmerge_end_users (only un-reverted merges can be undone).' This also names the related alternative tool and a key condition, providing clear 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 and destructiveHint=false, and the description reinforces this with 'Read-only; empty when none.' It adds behavioral details beyond the annotations: the exact fields returned and the empty result behavior. This is useful context for an agent deciding how to handle the response.

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 packed with information in three dense sentences plus a final usage note. Each sentence earns its place: the first defines the tool and its place in the hierarchy, the second lists return fields and empty behavior, the third gives usage direction. Slightly verbose but not wasteful.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers everything an agent needs: what it returns, how to use it in a workflow, and the empty-result behavior. The hierarchy context and explicit linkage to create/update tools make it complete.

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

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

Schema coverage is 100%, and the single parameter product_id is already fully described in the schema ('Only initiatives for this product, from whoami (optional; all products when omitted).'). The description adds no further parameter semantics beyond referencing initiative_id resolution, which is not about this parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the org's initiatives, defines them as the strategic layer between goals and features, and specifies the returned fields. It distinguishes from sibling tools by explaining the hierarchy (goal → initiative → feature → epic → release) and explicitly references the initiative_id usage for create_feature/update_feature/update_initiative.

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

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

The description provides clear usage context: it is read-only, returns empty when no initiatives exist, and should be used to resolve an initiative id before calling create_feature, update_feature, or update_initiative. While it doesn't explicitly list when not to use it or name alternative tools, the hierarchy explanation implies the niche.

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?

Though annotations already declare readOnly/idempotent/non-destructive, the description adds behavioral detail: 'returns matching insights newest first, empty when nothing matches', plus filter behavior and limit defaults. It does not contradict the annotations and provides context beyond the structured hints.

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 dense sentences front-load the core purpose, then enumerate filters and limit, then close with usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

Given a read-only search tool with 7 optional params and no output schema, the description covers purpose, filter set, ordering, empty behavior, and integration steps. It could be slightly more explicit about return fields, but the 'matching insights' phrasing plus schema makes it sufficient.

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

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

Schema covers all 7 parameters with descriptions, so baseline is 3. The description adds operational meaning by summarizing filters, noting 'free-text q over title+body', and advising how to resolve feature_id/account_id via sibling tools, which is helpful beyond the raw 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 explicitly states 'Search the captured insight backlog' with scope 'voice of customer', and identifies it as 'the read twin of capture_insight', clearly distinguishing this read tool from its write sibling. It specifies it returns matching insights newest first, with empty results when nothing matches.

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

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

Provides clear usage context: 'Use it to survey the evidence behind a feature or account before prioritising', plus resolution pointers (feature_id via list_features, account_id via get_customer_360). It does not explicitly state when not to use it, but names the write twin capture_insight as the alternative verb.

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 read-only, idempotent, and non-destructive hints. The description adds value by stating it is empty when no OKRs are set and defines the progress range (0..1). This supplements the annotation without contradiction.

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

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

The description is efficiently structured with a clear lead sentence, followed by return details and usage guidance. It is somewhat lengthy but every sentence contributes meaningful context, with no filler.

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

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

Given the simple nature of the tool, the description covers the return format, empty behavior, and usage guidance, which is sufficient. It lacks explicit pagination or ordering details, but these are not critical for a list tool with a single optional parameter.

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 optional product_id, and the schema description already documents the semantics. The description only restates 'Optional product_id, from whoami' without adding new 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 clearly states the tool lists the org's OKRs and specifies the return structure (objectives with key results and live progress). It is specific with a verb and resource, and the detail about progress distinguishes this list tool from sibling list tools.

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

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

The description explicitly advises using it before prioritising and explains how to use the output (tie tasks to objectives, cite progress). It does not explicitly mention alternatives or exclusions, but the context of use 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it returns only title+id (no content), is cheap to scan, and is empty when none exist. This is richer than the bare annotation hints.

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 focused sentences: first states the purpose, second covers output/behavior, third gives usage guidance and parameter mention. Every word earns its place with no redundancy.

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

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

Though there is no output schema, the description explains the return shape (array with title+id only), emptiness behavior, read-only safety, and integration with get_page and review_artifact. For a simple list tool with one optional parameter, this is fully complete.

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

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

The schema already fully documents product_id with 'Product id to scope to, from whoami (optional; spans all products when omitted)' at 100% coverage. The description merely repeats 'Optional product_id, from whoami' without adding new meaning, 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 it lists 'in-product docs / PRDs (Pages) on the spine' and explicitly distinguishes itself from get_page (which reads full content) and create_page. The verb 'List' plus the specific resource make the purpose unambiguous.

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

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

It provides explicit usage guidance: use it to find a page id before calling get_page, and pair with review_artifact for critiquing PRDs. It also notes the optional product_id scoping from whoami, giving clear context for 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 indicate read-only, non-destructive, idempotent. The description adds that it 'Returns an array, newest first' and is 'empty when nothing has shipped,' which are meaningful behavioral details beyond annotations. No contradiction exists.

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

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

The description is three sentences, each serving a purpose: defining behavior, giving usage context, and clarifying the parameter. It is front-loaded with the main action and avoids any fluff 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 simple read-only list tool with one optional parameter and no output schema, the description covers return shape, ordering, empty behavior, read-only nature, usage scenarios, and parameter source. It is complete enough for an agent to invoke correctly without additional context.

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 schema fully documents product_id including its optionality and source ('from whoami'). The description repeats this information ('Optional product_id, from whoami') without adding extra semantic value, so the baseline 3 applies.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List shipped releases.' It further specifies the output structure ('array, newest first') and content ('version, changelog, and ship date'), distinguishing it from related tools like get_roadmap_drift and create_release.

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

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

The description gives explicit use cases: 'answer what did we ship recently?', 'ground a changelog or launch summary', and 'see what went out before reading get_roadmap_drift.' It does not explicitly state when not to use it, but the contrast with get_roadmap_drift implies an alternative, so usage guidance is clear though not exhaustive.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds value by explaining return behavior: 'returns the matching sprints, empty when none exist,' and ordering 'newest first,' as well as the fields included. This goes beyond merely repeating the annotations. No contradiction detected.

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: three sentences that pack in the resource, ordering, read-only nature, empty result, use case, and filter example. Every sentence contributes information, and it is front-loaded with the core purpose. No redundancy or 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 simple list tool with one optional parameter and no output schema, the description covers all essential aspects: what is returned, ordering, empty result behavior, and a use case for sprint_id resolution. It even mentions a filter example. Given the low complexity, this is fully complete.

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

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

Schema description coverage is 100% and the description does not significantly add to the parameter meaning. It mentions 'Optional state filter (e.g. 'active')' which mirrors the schema's 'Filter by state, e.g. 'active' (optional).' Since the schema already fully documents the single parameter, the description provides no extra semantic value, so a baseline of 3 is appropriate.

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

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

The description clearly states that the tool lists sprints with name, goal, state, and window in newest-first order. It distinguishes itself from sibling tools (create_sprint, update_sprint) by focusing on a read-only listing of sprints, and it specifies the resource and what fields are returned.

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

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

It gives a concrete use case: 'resolve a sprint_id here before scheduling a task via create_task / update_task.' It also mentions 'See the delivery cadence (active + recent)' which implies when to use it for viewing sprint context. However, it does not explicitly say when not to use it or name alternatives beyond create_task/update_task, so it stops short of a full 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 cover read-only, idempotent, and non-destructive behavior. The description adds value beyond these by noting 'returns an empty list when nothing matches' and specifying that it returns linked features/insights/sprints. It also provides the behavioral note about resolving IDs via pm_meta, which is not in the annotations.

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

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

The description is efficient, with four concise sentences each providing distinct value: purpose, filtering options, behavioral note on empty results, and usage guidance. It is front-loaded with the core action and avoids extraneous information.

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

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

Given the tool's moderate complexity, the description covers purpose, filters, ID resolution, read-only behavior, empty-list return, and the task-id use case. An output schema exists, so return-value details are unnecessary. The description is fully self-sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with each parameter already described as optional and resolving via pm_meta. The description only echoes this guidance ('resolve either via pm_meta') without adding new semantic details. Baseline of 3 applies since 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 tool's function: 'List the org's board tasks' and specifies the returned fields (status, priority, assignees, linked feature/insight/sprint). It distinguishes from sibling tools like get_task by focusing on listing matches, and the final sentence positions it as a precursor to task-specific operations.

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

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

The description explicitly says 'Use it to find a task id before get_task, update_task, or comment_on_task', providing clear when-to-use context. It also instructs to resolve status_id or list_id via pm_meta. It does not explicitly state when not to use it, but the usage scenario is well-defined.

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

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

The description discloses critical behavioral traits beyond annotations: all FK rows are re-pointed, sources are tombstoned, and the operation is a write reversible for 30 days. This gives the agent full awareness of side effects and reversibility, especially important since annotations are all false.

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

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

The description is three sentences long, dense yet well-structured. It front-loads the core purpose and result, then efficiently conveys side effects, reversibility, and prerequisites without unnecessary verbosity.

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

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

For a complex write operation with no output schema, the description covers all essential context: the merge result includes the event id (retrievable later), FK re-pointing, tombstoning, reversibility window, and the mandatory prerequisite of using get_device_candidates. This is complete for an agent to decide and execute 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 input schema already provides thorough descriptions for all parameters (100% coverage), so the description adds minimal new parameter-specific semantics. It reiterates that the two IDs are required, which is already in the schema, but does not clarify any additional formats or constraints.

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

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

The description clearly states the action ('Merge source end-users into a target') and the expected result. It distinguishes itself from siblings by explicitly referencing related tools like get_device_candidates and unmerge_end_users, making its role unambiguous.

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

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

Provides explicit guidance: 'Get the candidate ids from get_device_candidates first — never guess which users to fold together.' This is a clear directive on when to use this tool and what prerequisite steps are needed. Also mentions unmerge_end_users for reversal, offering a complete usage context.

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

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

The description discloses that the tool is read-only and returns arrays 'for resolution only', which adds context beyond the readOnlyHint annotation by clarifying the limited, lookup-oriented purpose of the data. It also sets expectations about list_features being the richer source. No contradiction with annotations.

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

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

Two sentences, front-loaded with the primary action, and no superfluous content. Every sentence earns its place, providing purpose, usage, and a key warning efficiently.

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

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

For a zero-param, read-only lookup tool with no output schema, the description covers purpose, return format, usage context, and alternatives. It fully prepares the agent to invoke the tool correctly without additional ambiguity.

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 schema coverage is complete and no parameter documentation is needed. The description adds context about the output format (id+name pairs), which is useful for a resolution-only tool. Baseline for zero params is 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 clearly states the tool lists the org's PM lists, statuses, members, and features as id+name pairs, using a specific verb ('List') and resource scope. It also distinguishes itself from list_features by noting that list_features carries the richer catalogue, making the 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?

The description explicitly instructs when to use the tool: 'Call it to turn a name into an id before create_task / update_task' and warns against guessing ids. It also names the alternative tool (list_features) for richer data, providing clear guidance on tool selection.

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 indicate non-read-only, non-idempotent, and non-destructive. The description adds meaningful behavioral context by disclosing visibility ('appears live for teammates and is org-visible'), identity ('as the connected member'), and permission constraints ('only post to channels you're a member of'). This goes beyond the annotation booleans.

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 compact sentences with the core action first, followed by visibility caveat and usage prerequisite. Every sentence contributes necessary information with no redundancy or filler.

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

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

For a simple two-parameter tool with full schema coverage and no output schema, the description covers the action, audience, prerequisite, and constraints. It omits error handling or rate-limit specifics, but those are not critical for a basic post operation. The description is sufficiently complete for an agent to use this tool effectively.

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

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

The input schema already describes both parameters (100% coverage), so baseline is 3. The description adds valuable workflow guidance: channel_id must be resolved via list_channels and is limited by membership. This clarifies how to obtain and validate the parameter, which is 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 ('Post'), a clear resource ('a team Comms channel'), and a scope ('you belong to, as the connected member'). It also states the return value ('return the posted message'), making it distinct from siblings like read_channel and reply_in_channel.

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

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

The description provides a clear prerequisite ('Resolve channel_id via list_channels') and a membership constraint ('you can only post to channels you're a member of'). It implies when to use this tool (new post vs. reading or replying), but does not explicitly name alternatives or state when not to use it.

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 explicitly reveals idempotency ('Idempotent — an already-promoted idea returns its existing feature'), which is not declared in the annotations (idempotentHint: false). It also describes the state-changing effects: creates, stamps, links, and returns a feature id, providing substantial behavioral context beyond the annotations.

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

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

The description is three sentences, each serving a purpose: the first states the core behavior, the second reveals idempotency, and the third provides input guidance and a follow-up pointer. No filler or redundant repetition of annotations.

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 tool with no output schema, this description is complete: it covers the operation, the return value (feature id), idempotency, the required parameter origin, and a follow-up step. It leaves little ambiguity about what the tool does and how to invoke it.

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

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

The schema already covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by pointing to the source of the id ('Resolve the id via list_ideas') and clarifying that only id is required, which is helpful for correct invocation.

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

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

The description clearly states 'Promote an idea into a roadmap feature' and elaborates with the exact actions: creates a feature from the idea, stamps the idea 'promoted', links it to the new feature, and returns the feature id. This distinguishes it from sibling tools like create_feature or update_idea.

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 context on when to use: 'Promote an idea into a roadmap feature' and practical guidance such as resolving the id via list_ideas and only id being required. It also mentions a follow-up action with update_feature. However, it doesn't explicitly contrast with similar tools like create_feature or vote_idea, so it lacks a clear when-not-to-use statement.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds important context: the connected member must be a channel member, the return is empty when silent, and channel_id must be resolved via list_channels. These are beyond the annotations and clarify expected behavior.

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

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

Three concise sentences, each providing distinct information: what is read, membership requirement, and how to obtain channel_id. No redundancy or filler, 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?

With no output schema, the description mentions return contents and empty behavior. The membership requirement and resolution step are covered. It's complete enough for a safe read operation, though ordering beyond 'newest included' could be explicit.

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 both parameters. The description reinforces channel_id's source (list_channels) and notes limit is optional, which complements the schema's existing descriptions. This adds value rather than merely repeating schema 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 the tool reads a Comms channel's recent messages, specifying the resource ('Comms channel') and action ('read'). It also distinguishes from siblings like list_channels (which lists channels) and post_to_channel (which writes) by noting it returns messages and is read-only.

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

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

The description gives explicit prerequisite guidance: 'Resolve channel_id first with list_channels — never guess it.' It also notes the read-only nature and optional limit, but doesn't explicitly mention when to use this over alternatives like get_conversation. Still, the resolution instruction is valuable context.

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

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

Annotations already indicate a non-read, non-destructive mutation. The description adds meaningful context: the reply will be 'org-visible to the channel' and it will 'return the posted reply', clarifying the side effect and expected output. It does not mention rate limits or auth, but annotations cover the safety profile.

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

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

The description is two sentences, front-loaded with the purpose and side effect. The second sentence compactly delivers resolution guidance and required-parameter confirmation. No unnecessary words.

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

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

Given 3 required params, no output schema, and existing annotations, the description is complete: it covers purpose, membership requirement, visibility, return value, prerequisite resolution, and confirms required params. It fully enables 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?

Schema has 100% coverage with each parameter described, so baseline is 3. The description goes beyond schema by explicitly explaining that all three are required and providing resolution paths (channel_id via list_channels, parent_id via read_channel), which adds practical guidance.

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

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

The description clearly states the action: 'Reply in a thread under a specific message in a Comms channel you belong to', which is specific and differentiates from siblings like post_to_channel (top-level posts) and reply_to_conversation. It also includes the resource scope ('as the connected member') and return value.

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

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

The description provides explicit guidance on resolving channel_id via list_channels and parent_id via read_channel, which are necessary prerequisites. It clearly implies the context of replying to a thread but does not explicitly name alternatives or exclusions, so it is not a full 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 indicate readOnlyHint=false, so 'A write' is consistent and adds explicitness. The description enriches behavioral context by stating the reply is public, goes to the end-user, is sent as the connected member, and returns the result. This goes beyond the structured hints without contradicting them.

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

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

Two sentences pack all essential information: purpose, workflow, prerequisites, and alternatives. No redundant phrases; the em-dash structure front-loads the core action. Every sentence earns its place.

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

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

For a simple two-parameter write tool with no output schema, the description covers the purpose, actor, visibility, prerequisite steps, and sibling alternatives. It mentions 'return the result' but doesn't elaborate on return format or error cases, which would be a minor gap in completeness.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds workflow semantics for conversation_id ('from list_conversations') and clarifies that body is the 'public reply text' and that both are required. This provides value beyond the schema's 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 uses a specific verb and resource: 'Send a public reply to a support-inbox conversation' and adds scope ('as the connected member', 'goes to the end-user on the conversation's channel'). It clearly distinguishes from siblings like add_note and resolve_conversation by emphasizing 'public reply'.

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 workflow: 'Resolve conversation_id via list_conversations; read the thread with get_conversation before replying.' Also names alternatives and when-not-to-use: 'For an internal-only note use add_note; to close it use resolve_conversation.'

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 false and destructiveHint false. Description adds behavioral detail beyond annotations: 'A write' explicitly confirms mutation, and 'the invitee is notified' reveals a side effect. No contradiction between description and 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?

Description is compact and front-loaded, with the core action stated first. Minor redundancy exists: 'booking_id and start are required' duplicates schema, and 'A write.' is terse but still valuable as a safety signal.

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

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

For a simple two-parameter write operation with annotations present, the description covers the action, side effect (invitee notification), prerequisite (use list_bookings), and required parameters. Lack of return format is acceptable given no output schema and the simplicity of the tool.

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

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

Input schema covers both parameters fully with descriptions for ISO 8601 format and 'from list_bookings' provenance. Description redundantly states 'booking_id and start are required' and repeats the prerequisite, adding little beyond 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?

Description uses specific verb 'Reschedule' and resource 'a booking', specifies the new start time in ISO 8601, mentions returned result and invitee notification. This clearly distinguishes it from sibling tools like cancel_booking and list_bookings.

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

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

Provides clear context: 'Resolve booking_id via list_bookings first' directs the agent to a sibling tool and defines a prerequisite. It implies use for changing a booking time but does not explicitly exclude cancel_booking or state when not to use it.

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 useful context beyond annotations by explaining idempotency: 'resolving an already-resolved conversation is a no-op' and noting it 'return[s] the result.' It also categorizes it as 'A write' which aligns with readOnlyHint=false. No contradiction with annotations.

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

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

The description is three short sentences, each carrying distinct information: action, idempotency, and usage context. It front-loads the main purpose and avoids any 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 simple, single-parameter mutation tool with strong annotations and schema coverage, the description is fairly complete. It covers behavior, input provenance, and sequencing, though the nature of 'the result' is unspecified (no output schema).

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

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

The input schema already provides a full description of conversation_id, covering 100% of parameters. The description repeats the source ('via list_conversations') but adds no new 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 clearly states the verb and resource: 'Mark a support-inbox conversation resolved (closed) and return the result.' It distinguishes the tool from siblings like reply_to_conversation by focusing on the closing action.

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

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

The description provides clear when-to-use guidance: 'Resolve conversation_id via list_conversations first. Do it after you've replied and the ask is handled.' It implies the tool is for the final step but doesn't explicitly mention alternatives or 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?

The annotations already mark it as write-only and non-idempotent, but the description adds valuable context: the existing current version is flipped to 'reverted' and kept, and re-running reverts again. This explains the non-idempotency and the fate of the old version, going beyond the structured annotations. No contradiction.

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

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

The description is three concise sentences, each earning its place: the first explains the action and side effect, the second warns about non-idempotency, and the third clarifies parameter semantics. No fluff, and the most important 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?

Given its complexity (write operation with side effects), the description is complete: it covers the behavior, side effect, return value, parameter source, and non-idempotency. The lack of an output schema is acceptable since the description states what is returned. All necessary guidance for correct invocation 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?

With 100% schema coverage, the baseline is 3, but the description enriches the semantics by clarifying that version_id is the version to RESTORE (not delete) and providing its provenance via list_artifact_versions. It also notes the reason parameter is optional and recorded, adding nuance beyond the schema.

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

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

The description clearly states what the tool does: 'Restore an earlier artifact version (F5) to current' with a specific verb and resource. It also contrasts with siblings like list_artifact_versions and review_artifact by emphasizing the restore action and return value.

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

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

The description explicitly directs the agent to get version_id from list_artifact_versions and never guess it, providing a clear prerequisite and warning. However, it does not explicitly discuss when to use this tool versus alternatives or mention exclusions, so it falls just 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?

The description explicitly discloses that this is a write operation ('A write: each call re-runs the review and persists it as a new version'), which complements the annotations (readOnlyHint: false) and adds context about versioning and side effects. It also reveals 'One small LLM call' for cost/performance and notes the draft-only scope, going 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 dense but every clause earns its place: it covers purpose, criteria, output format, side effects, ID resolution, cost, and recommended timing. It is front-loaded with the core purpose and uses punctuation to separate concerns. 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?

Given there is no output schema, the description thoroughly explains the return payload (structured findings with section, severity, concrete suggested fix, verbatim quote, plus a score). It also covers prerequisites (target_id resolution), side effects (persists new version), and use case ('before sending a draft for sign-off'). 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 coverage is 100%, so the baseline is 3. The description adds value by explaining how to resolve target_id (via pm_meta or list_* tools) and by clarifying the target_type semantics (feature = spec, experiment = plan, page = doc/PRD). This enriches the bare schema without redundancy.

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 this is an 'Agent-as-critic' review tool for DRAFT artifacts, specifying the artifact types (feature spec, experiment plan, page), the review criteria (baseline PM bar), and the structured output (findings plus 0-100 score). It distinguishes itself from sibling tools like get_page or update_page by emphasizing it checks and critiques rather than reads or edits.

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

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

The description provides clear usage context: 'use it before sending a draft for sign-off' and instructs to 'Resolve target_id first' via specific sibling tools (pm_meta, list_features, list_experiments, list_pages). It does not explicitly say when not to use it or name direct alternatives, but the context is strong and actionable.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals that the tool reads a merge ledger, re-points foreign keys, un-tombstones sources, and fails with 'already_reverted' on retry. This enriches the idempotentHint=true annotation without contradicting any annotation.

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

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

The description is three sentences of tightly packed, relevant information with no fluff. The purpose is front-loaded, followed by behavioral details and usage instructions. Every sentence earns its place.

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

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

For a one-parameter, no-output-schema tool, the description is remarkably complete: it covers the operational mechanism, retry behavior, use case, and how to source the parameter. There are no obvious gaps that would leave an agent uncertain.

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 already documents event_id with 100% coverage, the description adds practical sourcing instructions: find it via list_identity_merges and pick an un-reverted merge. This guidance goes beyond schema descriptions, turning a raw ID field into a fully actionable 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 'Undo a previous end-user merge,' which is a specific verb+resource statement. It further distinguishes the tool from its sibling merge_end_users by detailing the mechanics (re-pointing FK rows, un-tombstoning sources), making the 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?

The description explicitly states when to use it ('Use to correct a wrong identity merge') and adds a temporal constraint ('merges stay reversible for 30 days'). It also tells the user how to obtain the required event_id via list_identity_merges, providing clear invocation 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?

The description adds substantial context beyond the annotations: partial updates ('omitted fields unchanged'), side effect of status change ('re-stamps the decision time'), link verification ('verified in-org'), and clearing with nulls. This goes well beyond the idempotentHint and destructiveHint provided.

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 primary action in the first sentence. Every sentence adds useful behavioral or operational detail without padding or redundancy.

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

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

Given the absence of an output schema, the description adequately covers return behavior ('return it'), id resolution, field semantics, and special cases like relinking and clearing. It is complete for safe invocation of this update operation.

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

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

Even though schema coverage is 100%, the description adds critical semantics: 'omitted fields unchanged', 'only id is required', and the relationship between link_type and link_id ('Re-link via link_type + link_id ... or clear with nulls'). This meaningfully enhances 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 ('Update a decision and return it'), clearly distinguishing it from create_decision and list_decisions. It also states key behavioral scope with 'omitted fields unchanged', making the tool's purpose unambiguous.

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

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

Provides clear usage context: 'Resolve the id via list_decisions; only id is required' tells the agent how to obtain the required identifier. It also explains optional behaviors like status re-stamping and link handling, though it does not explicitly state when not to use this tool versus alternatives.

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