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

Annotations already indicate this is a write operation (readOnlyHint false). The description adds that the note is internal and visible only to the team, and that it returns the result. No contradiction with annotations.

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

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

Three efficient sentences: purpose, usage guidelines, and required parameters. No wasted words, front-loaded with key 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 2-param tool with no output schema, the description fully covers purpose, behavior, prerequisites, and alternatives. Nothing missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that conversation_id should be resolved via list_conversations and that the body is for teammates-only, which goes beyond the schema descriptions.

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

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

The description clearly states the action ('Add'), the resource ('INTERNAL note to a support conversation'), and distinguishes it from the sibling tool 'reply_to_conversation' by specifying it is team-only and never sent to the end-user.

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

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

Explicitly states when to use ('record context or hand off'), how to find the required conversation_id (via list_conversations), and when not to use (for 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 indicate readonly, idempotent, non-destructive. Description adds essential behavioral details: evaluation order matters, returns empty counts on no match, and prerequisites (needs events flowing) 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?

Four sentences, all adding value: purpose, usage guideline, prerequisite, parameter help. Front-loaded with main function. Slightly wordy but 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?

No output schema, but description explains return metrics (distinct users, conversion %, drop-off) and empty behavior. Mentions prerequisite and sibling tool. Could hint at pagination or ordering details, but sufficient for 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 covers all 3 parameters with descriptions. Description adds valuable context: suggests calling with no steps to get menu, clarifies window_days default and valid range (1-365), and explains product_id optionality referencing whoami.

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 clearly states the tool builds a conversion funnel with specific metrics (distinct users, step-to-step conversion %, drop-off) and explicitly distinguishes from sibling tool analyze_paths by stating it pairs with it to see 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?

Provides explicit when-to-use guidance: call without steps to get menu of events, pairs with analyze_paths, requires product-analytics events, and explains behavior when no events match.

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, non-destructive. The description adds that computation is deterministic, based on survey responses within a window, and returns empty if no responses. It also notes product_id optional and default window. This adds value 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?

Three sentences, front-loaded with main outputs, efficient. Every sentence adds value 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?

Despite no output schema, the description explains all returned items (scores, weighted NPS, detractor accounts) and edge cases (empty result). With two simple params and no nested objects, it is 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%, so baseline is 3. The description adds minor elaboration (e.g., 'last quarter' for window_days, 'primary product' for product_id) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool computes standard and revenue-weighted NPS along with detractor ranking. It uses specific terms like 'NPS for the product' and lists outputs, making the purpose unambiguous.

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

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

The description gives implicit workflow guidance: 'Quantify sentiment after get_product_brain, then dig into a detractor with get_customer_360.' It also hints at when to use by highlighting a scenario (biggest customers unhappy). No explicit when-not-to or alternatives, but context is clear.

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

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

The description aligns with annotations (readOnly, idempotent, not destructive) and adds behavioral details: computation is deterministic, uses subscription movements within window_days, returns empty when no data falls in the window, and the window range is 1–365. This is transparent and covers key behavior 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 concise and dense with useful information. Every sentence serves a purpose: defining outputs, explaining the concept, noting computation details, and providing a usage recommendation. There is no repetition or filler, making it efficient for an AI agent to parse.

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

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

Given there is no output schema, the description adequately covers what the tool returns (NRR, logo retention, split, top-losing accounts) and how it works (deterministic, window-based). For a tool with one optional parameter, this provides sufficient context for an AI 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%, so baseline is 3. The description enhances the parameter by explaining the default value (90 days, 'i.e. the last quarter') and the valid range. This adds practical context that helps the agent understand the parameter's meaning and 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 that the tool computes Net Revenue Retention (NRR) along with logo retention, expansion/contraction/churn split, and a ranked list of top-losing accounts. It distinguishes itself from sibling analytics tools like analyze_nps and get_retention by specifying revenue-weighted metrics and a focus on highest-loss accounts.

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

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

The description provides clear guidance on when to use the tool ('Quantify revenue health') and suggests a follow-up action ('follow the top-losing accounts into get_customer_360'). However, it does not explicitly exclude scenarios where other retention tools might be more appropriate, so there is mild room for improvement.

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 readOnly, idempotent, and non-destructive behavior. The description adds that results are empty when no events match and that transitions are ranked by user count, plus notes that the tool uses the product's own events. This adds context without contradicting 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 core purpose, and then concise parameter guidance. No wasted words; every sentence earns its place.

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

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

Given no output schema, the description adequately covers the return type (ranked transitions, empty when no matches). It also explains parameter defaults and valid ranges. A slight gap is the lack of detail on the structure of a transition, but it is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful extra context: for 'start', it explains that omitting uses the most common start and references analyze_funnel; for 'window_days', it provides default and valid range; for 'product_id', it directs to whoami. This significantly aids an AI agent.

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 traces user actions after a start event, returning a journey flow as a Sankey diagram ranked by user count. It distinguishes itself from sibling tools like analyze_funnel by specifying the focus on post-event transitions.

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 when to use the tool (to see next-step transitions after an event) and provides an explicit alternative for listing event names via analyze_funnel. However, it does not explicitly state when not to use it, such as for cumulative metrics.

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 (write) and idempotentHint=true. The description adds that the invitee is notified per settings, enhancing transparency 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?

Three sentences: purpose, behavior, and sibling guidance. Front-loaded, efficient, no redundancy.

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

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

With 1 parameter, no output schema, and annotations present, the description suffices: covers usage, parameter source, and behavioral note. Nothing missing.

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

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

Schema covers booking_id with description; the tool description adds valuable guidance to resolve via list_bookings and never guess, improving parameter meaning.

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

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

The description clearly states it cancels a booking, distinguishing from reschedule_booking. It specifies the action, resource, and outcome (invitee notified).

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

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

Provides explicit when-to-use: resolve booking_id from list_bookings first; and when-not-to: use reschedule_booking for moving. Offers clear context and alternative.

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

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

The description discloses that the tool fires the same insight.created webhook as a manual capture, indicating a real side-effect. This adds behavioral context beyond the annotations (which already mark readOnlyHint=false). It does not contradict any 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, with the main action front-loaded. Each sentence contributes essential information (function, side-effect, parameter guidance). It is efficiently written without extraneous content.

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

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

Given the tool has 6 parameters (1 required) and no output schema, the description covers the return value (created insight), side-effect, and parameter sourcing. It is complete enough for a creation tool, though it could elabor on error handling or idempotency, but annotations already address idempotency as false.

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 description still adds significant value by telling how to source parameter values (e.g., account_id from get_customer_360, feature_id from list_features) and clarifying that kind='opportunity' marks a prioritisable ask. This goes beyond the schema's field descriptions.

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

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

The description uses a specific verb 'Write' and resource 'customer feedback to the spine', clearly distinguishing it from siblings like create_feature or create_task. It also mentions returning the created insight, leaving no ambiguity about the tool's function.

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 to 'only capture genuine signal' and provides guidance on resolving account_id and feature_id from specific tools (get_customer_360, list_features). It explains the role of kind='opportunity', offering clear context for when to use this tool versus other creation tools, though it lacks explicit when-not-to-use statements.

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 indicate mutation and non-destructiveness. Description adds that comments are authored as the connected member, visible to the whole org, and returns the created comment—valuable 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?

Two sentences, no wasted words, front-loaded with core action. Efficient and clear.

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

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

Covers purpose, usage, prerequisites, visibility, and return value. No output schema, but the description sufficiently explains what to expect. Minor gap on format of returned comment, but 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?

Schema coverage is 100%, so baseline is 3. Description reiterates schema info (both required) with minor context (id from get_task/list_tasks, body visible). Adds marginal meaning.

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

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

The description clearly states the action (add a comment), the target (task), and authorship (connected member). It distinguishes from siblings like create_task or update_task by focusing on commenting.

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 when-to-use examples (record progress, decision, handoff) and prerequisites (resolve task id). No explicit when-not-to-use, but the context is clear.

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

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

The annotations provide no behavioral hints, so the description carries the full burden. It discloses that a 'decided' status stamps the decision time, linking is verified in-org, and the tool returns the decision. This adds meaningful behavioral context beyond the schema.

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

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

The description is extremely concise—two sentences that front-load the primary action and then unpack key details. No redundant words or 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 create tool with 5 parameters and no output schema, the description covers the main points: required field, status options, linking behavior, and verification. It is missing details on error handling or return format, but these are not critical for agents.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the side effect of 'decided' status (timestamps) and that link_id is verified in-org, which is not in the schema descriptions.

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

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

The description states the verb 'Log' and resource 'decision', and clarifies that the tool creates a decision record. It also distinguishes the decision's status options and linking capability, though it doesn't explicitly contrast with sibling tools like create_feature or create_objective.

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

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

The description implies usage by mentioning required and optional fields, and suggests linking to other entities. However, it does not explicitly state when to use this tool versus alternatives (e.g., update_decision or list_decisions) or provide exclusion criteria.

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?

Description adds return behavior and state enumeration beyond annotations, but does not mention side effects, permissions, or limitations. Annotations already indicate non-readOnly, so the added value is moderate.

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

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

Two sentences, each earning its place: first defines action and object, second clarifies state values, required field, and context against sibling tool. 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?

Covers creation, required fields, state options, and differentiates from analytics engine. Does not describe return structure or relationships, but is fairly complete given no output schema and 6 parameters.

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. Description reinforces that only title is required and explains state enum, but does not add significant new meaning beyond 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?

Clearly states it creates a PM experiment (a Build-Measure-Learn hypothesis) and returns it. Distinguishes from the analytics A/B engine via explicit mention.

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 implies use for PM experiment creation and distinguishes from A/B testing tool. Does not explicitly specify when to use vs other Create tools, but 'only title is required' gives helpful usage guidance.

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

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

Annotations are present and the description adds behavioral details beyond them: key generated from name, status starts 'active', product_id defaults to primary product. No contradictions. The description provides useful context without being redundant.

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 that are front-loaded with the main purpose. Every word earns its place. No extraneous information. Highly efficient.

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

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

Given the tool has 5 parameters and no output schema, the description covers the key points: required fields, defaults, return values, and usage context with create_task. It does not explain error handling or edge cases, but for a create tool this is reasonable.

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 an example and clarifies the key generation and product_id default, but the parameter descriptions in the schema already adequately document each field. Minimal added 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 verb 'create' and resource 'feature', specifies the return values (id, key, name, status), and explains key generation and default status. It distinguishes the tool from siblings like create_task by stating the order of operations.

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

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

The description gives explicit guidance on when to use this tool ('create a feature here before linking tasks to it with create_task') and explains the default behavior for product_id. It does not explicitly state when not to use, but the context is clear enough for an AI agent.

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

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

Discloses default behavior (status 'new', 0 votes, product_id defaults to primary product) and links to evidence via insight_id. Annotations are consistent; description adds value beyond 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?

Three sentences, front-loaded with purpose, each sentence adds value. Efficient 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?

Complete for a creation tool: explains what is returned, required/optional fields, defaults, and workflow context. No output schema, but description compensates.

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 4 params (100%). Description adds extra meaning: default values for votes/status, product_id default, relationship of insight_id, and that only title is required.

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?

Clearly states 'Create an idea in the backlog and return it'. Specific verb+resource, distinguishes from siblings like update_idea, list_ideas, vote_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?

Provides clear context for when to use (creating an idea) and gives workflow hints ('Grow it with vote_idea, then promote_idea'). However, no explicit exclusions or when-not-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?

Annotations show non-readonly, non-destructive, creation behavior. Description adds defaults (status='planned', product_id from primary product), fact that it returns the initiative, and how to build line-of-sight. 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?

Single paragraph with no fluff; first sentence captures purpose. Every sentence adds value: resource definition, linking, defaults, required field, post-creation steps.

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

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

Covers all key aspects for a creation tool: purpose, parameters, defaults, downstream actions. Lacks return value format (no output schema) and error handling, but sufficient for agent selection.

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 100%, and description adds extra context: explains purpose of objective_id, defaults for product_id and status, enum values, and that only name is required. Provides example usage.

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 clearly states 'Create an initiative' with specifics on what an initiative is (strategic effort grouping features, rolling up to goal). Distinguishes from siblings by mentioning linking to goals and aligning features via other 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?

Explicitly advises when to use: creating initiatives, linking to goals via objective_id. Provides prerequisite (use list_objectives) and follow-up actions (create_feature/update_feature). Lacks explicit when-not-to-use but context is clear.

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

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

Annotations indicate readOnlyHint=false, which aligns with the mutation action described. The description adds that fields are verified in-org, but does not cover all behavioral traits (e.g., atomicity of key result creation). No contradictions 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 two sentences, front-loaded with the main action, and contains no redundant information. Every sentence adds value.

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

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

The description covers the core creation action and key constraints. While it lacks details on return format (e.g., includes objective ID), it is adequate given the schema richness and lack of output schema. It could be more complete but is not deficient.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by explaining free-text period, verification of IDs, and key result structure. This helps the agent understand parameter usage beyond the basic schema properties.

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 'Create an objective, optionally with key results, and return it.' It uses a specific verb and resource and distinguishes itself from sibling tools like update_objective and list_objectives.

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

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

The description provides context on optional fields and constraints (e.g., period is free text, product_id/parent_id verified in-org). However, it does not explicitly state when to use this tool versus alternatives like update_objective, though it is implied.

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 indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds context about body parsing, default title, and verification of product_id/parent_id in the organization, 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?

The description is very concise, using two sentences that front-load the core action and return value, then details parameters efficiently with no extraneous content.

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

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

Given 5 optional parameters, no output schema, and existing annotations, the description adequately covers creation behavior, return format, and key constraints. It lacks details on the icon parameter beyond being optional, but overall is 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 coverage is 100%, so baseline is 3. The description adds value by explaining body formatting (blank lines create paragraphs), title default, and that product_id/parent_id are verified in-org, which the schema's descriptions (just 'optional') do not convey.

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 ('Create') and resource ('a Page'), specifies it returns id and title, and explains the body format and defaults. It distinguishes itself from siblings like update_page and list_pages by focusing on creation.

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 when to use the tool (to create a page), but does not explicitly state when not to use it or mention alternatives like update_page. However, the sibling context makes the distinction 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 (all false) indicate the tool is not read-only, not idempotent, not destructive, and not open-world. The description aligns by stating it 'Create a release', implying a side effect. It adds behavioral details about return fields and draft behavior, but does not discuss permissions, rate limits, or potential failures. The description carries some burden but is not exhaustive.

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

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

The description is two efficient sentences. The first sentence front-loads the primary purpose and output fields. The second sentence provides essential parameter guidance. No extraneous 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 no output schema, the description explicitly lists the return fields. It covers all parameter semantics and default behavior. However, it omits potential error scenarios (e.g., duplicate version) and lifecycle interactions (e.g., effect on related entities). Still, for a create tool, it is adequately complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond property descriptions: it clarifies the default for 'product_id' and the semantics of omitting 'released_at' for drafts. This compensates for the schema's lack of such context.

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

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

The description clearly states the tool's purpose: 'Create a release and return it (id, version, changelog, released_at).' It uses a specific verb ('Create') and resource ('release'), and distinguishes from siblings like 'update_release' by being the creation counterpart.

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

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

The description provides context on when to omit 'released_at' for drafts and notes that 'product_id' defaults to the primary product. It also specifies that only 'version' is required. However, it does not explicitly advise when to use this tool over alternatives like 'update_release' or 'list_releases', which would strengthen this dimension.

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 clearly discloses that the tool creates a resource (consistent with readOnlyHint=false), returns specific fields, and sets a default state. It adds behavioral context beyond annotations, such as mentioning that start_date/end_date are optional ISO 8601 strings and that the returned id can be used for task scheduling. 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, each packing essential information without redundancy. The main action and return are front-loaded, and the post-creation usage tip is a natural extension.

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

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

Given the lack of an output schema, the description compensates by listing return fields. It provides sufficient context for a straightforward creation tool with 5 parameters and full schema descriptions. Minor gaps: no mention of error conditions or permissions, but not critical for this 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 the description primarily reinforces schema info (name required, state default). It adds marginal value by explicitly stating 'Only name is required' and hinting at the purpose of the return value (for task scheduling), but does not enrich parameter meaning 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 starts with a specific verb-resource pair ('Create a sprint') and lists the returned fields (id, name, goal, state, dates). It clearly distinguishes from sibling tools like update_sprint and list_sprints by focusing solely on creation and hinting at downstream integration with create_task/update_task.

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 states 'Only name is required' and explains optional fields and defaults (state defaults to 'future'). It provides post-creation guidance on scheduling tasks via sprint_id. However, it does not explicitly state when to prefer this tool over alternatives like update_sprint or list_sprints.

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 the tool is not read-only and not destructive. The description adds behavioral context: defaults (list_id), linking to spine/sprint, and that only title is required. No contradictions with annotations.

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

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

The description is two sentences with no wasted words. First sentence states purpose and return value; second sentence provides critical usage guidance. Highly efficient.

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

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

Given 9 parameters, 100% schema coverage, and no output schema, the description adds sufficient integration context (ID resolution, defaults). It does not cover error handling or response format, but for a creation tool the description is adequate.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by explaining defaults (list_id) and ID resolution methods, which goes beyond 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 clearly states the tool creates a task and returns it, with specific verb-resource pairing. It distinguishes from siblings like update_task and delete_task by focusing on creation. The description also clarifies default behavior and linking parameters.

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 how to resolve IDs via pm_meta and list_sprints, and warns against guessing. It implicitly directs when to use this tool (creation) versus siblings, but lacks an explicit exclusion statement for alternative tools.

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

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

Beyond the destructiveHint annotation, the description details irreversible cascading deletion of comments, assignees, tags, attachments, time entries, outcomes, events, relations, subtasks, and clearing of experiment/insight/meeting links. It also discloses the return value (deleted id), providing essential safety context. 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?

Compact three-sentence description, front-loaded with the critical permanence warning. Every sentence earns its place—irreversibility, cascading effects, and usage alternatives—with 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 destructive mutation tool, the description covers preconditions (resolve id, confirm), cascading effects, and return value despite lacking an output schema. The rich annotations and schema complement this well, making it effectively 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%, so baseline is 3. The description adds value by telling how to obtain the id (via list_tasks) and emphasizing the need for confirmation, which complements the schema's confirm parameter description. This slight extra guidance justifies 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 'PERMANENTLY delete a task and return the deleted id,' giving a specific verb, resource, and outcome. It clearly distinguishes itself from siblings like update_task and list_tasks by emphasizing irreversibility and deletion 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?

Explicitly instructs to resolve the id via list_tasks and confirm intent first, and recommends update_task as a safer alternative when only removing from the active board. This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context that the map is auto-generated and returns empty when not yet generated, which is useful 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 well-structured with a clear opening, usage guidance, and parameter note. It is slightly verbose but every sentence adds value; could be tightened but still effective.

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 fully explains the return content (summary, counts, etc.) and edge case (empty when not generated). It covers the single optional parameter and provides usage context, making it complete 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?

Schema coverage is 100% with a description for product_id. The description adds that it comes from whoami and omission defaults to the org's primary product, providing extra 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 returns an 'auto-generated codebase brain map for one product' and lists its contents (summary, counts, timestamps, module labels). It distinguishes from all sibling tools by being the only codebase-map-focused tool.

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

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

Explicitly advises using it to answer 'where in the code does X live?' questions and before discussing architecture. It also explains the optional product_id behavior. However, it doesn't explicitly state when not to use it or name alternatives, though no direct alternatives exist among 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?

Description adds read-only affirmation (aligns with readOnlyHint) and details ordering (oldest first) and content (visitor + thread), complementing 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 purpose, each sentence necessary and efficient.

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

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

Despite no output schema, description explains return content and ordering, and parameter semantics are fully addressed. No gaps.

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

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

Schema describes conversation_id as from list_conversations; description reinforces this with explicit instructions and warning, adding significant context 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 reads a support conversation including visitor and full message thread, oldest first. It distinguishes from list_conversations (which lists conversations) and other 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?

Explicitly instructs to resolve conversation_id using list_conversations and never guess it, providing clear prerequisite and prohibition.

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 indicate readOnlyHint=true and destructiveHint=false, and the description confirms 'Read-only'. It also adds that it returns an empty result on no match and that data is joined from multiple sources, beyond what annotations cover.

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

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

The description is two sentences with no fluff. It front-loads the core purpose and scoping, making it efficient for an agent to parse.

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

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

Despite no output schema, the description sufficiently explains the return structure (profile, subscription+MRR, users, feedback) and the join concept. This covers the agent's need for outcome understanding.

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

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

The schema covers the single parameter 'query' with 100% description of its possible values (id, email, domain, company name). The description adds usage context but no new parameter-level detail, 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 fetches everything about one customer using multiple identifiers (id, email, domain, company name) and lists specific fields (profile, subscription+MRR, users, feedback). This distinguishes it from sibling tools like get_conversation or list_tasks.

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 advises calling it 'before answering anything about a specific account' and notes it is read-only. While it doesn't explicitly exclude other use cases, the context is clear enough.

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

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

The description discloses the tool is 'Read-only' and returns 'empty when none are found.' It provides additional context beyond annotations by explaining the two cluster types and their confidence levels. No contradictions with annotations (readOnlyHint=true, destructiveHint=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 two sentences long, front-loaded with the core function, and contains no redundant information. Every sentence adds value.

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

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

Given no output schema, the description explains what is returned (clusters of end users with two types) and that it can be empty. This is mostly complete, though it could explicitly state the return type (e.g., a list).

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

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

There are no parameters, and the schema coverage is 100%. The description implicitly clarifies that no input is needed, which aligns with the empty schema. No additional parameter semantics 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 that the tool returns clusters of end users seen on the same device, distinguishing two types ('anon_bridge' and 'device_shared') with confidence levels. It also explicitly ties to the use case of finding merge targets, differentiating it from sibling tools like merge_end_users.

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

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

The description explicitly guides usage: 'Use it to find merge targets, then act with merge_end_users.' This provides clear context for when to use this tool vs. alternatives. It lacks explicit when-not-to-use scenarios, but the clear purpose makes the guidance sufficient.

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. Description adds 'Read-only' and states it returns 'full content', reinforcing safe behavior. 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?

Two concise sentences, front-loaded with the action, no superfluous 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?

Simple read tool with one parameter, annotations cover behavioral traits fully, and description adequately explains output. Complete for its 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 has 100% coverage with a 'from list_pages' hint, and the description adds further context that the id must come from list_pages, complementing 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?

Description clearly states 'Read one Page' with specific resource 'Page (doc / PRD)' and outcome 'return its full content'. Distinguishes from sibling tools like list_pages (listing) and update_page (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?

Explicitly instructs to 'Resolve the id first with list_pages — never guess it', providing clear prerequisite and a constraint on usage.

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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds that it has 'no side effects', is 'deterministic', and describes the content of the guide. This goes beyond annotations by detailing what the guide contains and how it behaves, with no contradictions.

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

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

Single paragraph, front-loaded with purpose and usage. The description is concise but slightly lengthy due to listing guide contents. Every sentence adds value, though some could be tighter. Still, it is 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?

Given no parameters and no output schema, the description is complete. It explains the return value (plain text guide), determinism, and a high-level summary of content. Rich annotations cover behavioral aspects. No further information is needed.

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 has no parameters (100% coverage). The description briefly states 'No arguments', which is sufficient. Baseline for 0 parameters is 4, and no additional parameter semantics are needed or provided.

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

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

The description clearly states it returns an operating guide for PM on AIOProductOS, a specific verb+resource. It distinguishes itself from sibling tools by being deterministic, having no arguments, and being a 'first call' prerequisite.

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 'Call it FIRST, before planning or prioritising', providing clear when-to-use. Does not explicitly exclude alternatives or state when not to use, but the 'FIRST' implies it is a prerequisite. No explicit alternative naming, but context with siblings suggests it loads rules assumed by others.

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. Description adds that blocks are empty when sources aren't flowing and that time-windowed sections honor the `window` parameter. 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?

Description is moderately sized but every sentence contributes value. It is well-structured, starting with the purpose, then detailing return content, then usage guidance. Could be slightly tighter but effective.

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 explains the return structure (JSON with blocks) and handles both parameters. It covers edge cases (empty blocks) and dependencies (window). Sufficient for a single-call 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%, with both parameters already described. The description adds minimal extra meaning: it explains which sections the window applies to and that product_id defaults to primary product. 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 uses specific verbs ('get a grounded snapshot') and clearly states it returns revenue, accounts, analytics, features, customer signals, and work counts. It distinguishes from sibling tools by advising to 'start here to ground, then go deeper with dedicated list_* reads.'

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

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

Explicitly tells when to use this tool ('start here to ground') and directs to alternatives ('go deeper with dedicated list_* reads and analytics tools'). Also notes single call, no pagination, and optional product_id.

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

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

Annotations already indicate read-only and idempotent; the description adds the specific retention structure, window_days meaning, and product_id optionality, providing useful behavioral context 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?

The description is a single paragraph that efficiently conveys the core concept, structure, and key parameters without fluff. Every sentence adds value.

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

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

Given the simple parameter set (2 optional params) and no output schema, the description fully covers what the tool does, when to use it, and what to expect. No gaps.

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

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

Schema coverage is 100%, but the description adds value by explaining the default window_days in terms of cohorts (56 = 8 weekly) and the optionality of product_id (primary product when omitted).

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 provides 'weekly cohort retention' with a specific structure ('lower-triangular grid'), and it distinguishes from siblings by its analytic nature (focused on retention metrics).

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 specifies prerequisites ('Needs product-analytics events flowing') and behavior when conditions aren't met ('returns empty cohorts'), providing context for when to use 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context: deterministic, no LLM cost, edge case 'zeroed when nothing was planned or shipped'. Enhances understanding 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 sentences, front-loaded with core output, then behavioral details and usage advice. Every sentence adds value with no redundancy.

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

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

No output schema, but description fully lists return fields (drift score, counts, median slip days, top slipped/unplanned ships) and covers edge case. Complete for an AI agent to understand and use 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%, but description adds functional context: explains window options with default quarter, product_id optional and from whoami, and clarifies that omitting product_id spans whole org. Provides usage-relevant meaning.

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

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

Clearly states the tool returns 'planned vs shipped features over a window' with specific metrics (drift score, counts, median slip days). Distinguishes from siblings by naming a follow-up action with list_features, implying uniqueness in providing drift analysis.

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 recommends using it in 'planning reviews to check delivery against the roadmap' and suggests a next step. Lacks explicit when-not or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral detail: returns full comments and assignees, reinforces read-only nature, and emphasizes id provenance. 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?

Two sentences with no wasted words. First sentence states purpose, second gives actionable guidance. Front-loaded with clear verb and object.

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 rich annotations, this description covers purpose, return content, id sourcing, and composition with sibling tools. No output schema needed. Completely adequate for effective 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 covers 100% of parameters with description 'Task id, from list_tasks.' Description adds crucial context by explicitly stating 'Resolve the id first with list_tasks — never guess it,' clarifying the parameter's source and usage.

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?

Clearly states 'Get one task by id' with specific resource and scope. Specifies return includes 'full comments and assignees'. Distinguishes itself from sibling tools like update_task and comment_on_task by contrasting read vs. write roles.

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 to resolve id with list_tasks first and never guess it. Also instructs to pair with update_task or comment_on_task for subsequent actions, providing clear when-to-use and when-not-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 adds that the memo is deterministic (based on real rows, no fabricated quotes) and read-only except for the generate rebuild. This complements the annotations (readOnlyHint, idempotentHint) by explaining the rebuild behavior and the absence of quotes. It provides useful behavioral context 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?

The description is three sentences long and front-loaded with the core output. Each sentence provides distinct value (output content, behavioral traits, usage guidance). It could be slightly more concise, but it is well-structured and informative.

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

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

Given the tool's complexity (clustered themes, multiple data categories) and the absence of an output schema, the description thoroughly explains what the memo contains (themes, quotes, deltas, experiments, releases) and its behavior (deterministic, empty when none). This is complete for the user to understand what to expect.

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

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

The description adds significant meaning beyond the input schema: it specifies the ISO week format ('YYYY-Www'), explains that generate='1' rebuilds and persists the memo, and clarifies that both are optional. This fully compensates for the schema's simple 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 returns the Weekly Product Signal Memo, a clustered summary of customer signals with themes, deltas, experiments, and releases. It distinguishes itself from the sibling 'list_insights' by indicating that list_insights is used for drilling into a theme after viewing the memo.

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 suggests using the tool to open a weekly review and then drill into a theme with list_insights. It explains the optional week and generate parameters, providing clear context for usage. However, it does not explicitly state when not to use it or list alternatives beyond list_insights.

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 false, idempotentHint true. Description adds that it's read-only and returns version list with details (score, model, cost, etc.), empty when never reviewed. 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?

Single paragraph of three sentences, front-loaded with purpose, includes all necessary information 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?

No output schema, so description bears the burden. It mentions return fields (score, model, cost, etc.), empty case, and relationship to revert_to_version. Lacks pagination or ordering details, but adequate for a list endpoint.

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 descriptions. Description adds value by cross-referencing parameters to review_artifact, e.g., 'takes the same target_id/target_type you'd pass to review_artifact.' This contextual tie-in is helpful.

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?

Clearly states it lists version history of AI reviews for an artifact, specifying the verb 'list' and resource 'artifact versions'. Distinguishes from siblings like review_artifact and revert_to_version by explaining it provides data for the latter.

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 review changes over time and to pick version_id for revert_to_version. Also ties parameters to review_artifact. No negative guidance, but the context is sufficient.

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, non-destructive. The description adds context that results are empty when none are scheduled and clarifies the parameter's effect on history retrieval. 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?

Three short sentences with no fluff. The first sentence is a noun phrase instead of an active verb phrase, slightly reducing clarity, but overall very concise.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description covers the main purpose, parameter behavior, and return scenario. Adequate for an agent to use 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% for the only parameter. The description repeats the schema's instruction ('Pass include='all' for history') with slight rewording, adding marginal value. Falls at baseline for high coverage.

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

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

The description clearly states the action (list) and resource (bookings), specifying 'upcoming confirmed' which differentiates it from other list tools. It also explains the effect of the optional parameter.

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

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

The description implies usage for viewing upcoming bookings and mentions the include parameter for history, but does not provide explicit guidance on when not to use this tool or direct comparisons to sibling tools like cancel_booking or reschedule_booking.

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. Description adds the detail of returning empty when member belongs to no channels, which is useful but minimal 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?

Two concise sentences. Front-loaded with primary purpose, then usage note. 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?

Fully covers the tool's behavior given zero parameters and no output schema. Mentions empty result and directs to related tool for single read.

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?

No parameters, so baseline 4 applies. Description does not need to add parameter information.

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 team Comms channels scoped to membership, specifies read-only, and notes empty case. It distinguishes from read_channel by suggesting using that tool to read 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?

Explicitly directs to use read_channel for reading a single channel, providing a clear alternative. Does not explicitly state when not to use, but context is sufficient.

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. The description adds that the tool is 'Read-only' and returns 'empty when the inbox is clear', which is useful behavioral info beyond 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 two sentences, front-loading the main purpose and default behavior. It is efficient and well-structured, with 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?

The description explains the return value (matching conversations, empty when clear) and covers optional parameters. With no output schema, this is sufficient. The tool is simple and the description adequately supports selection among siblings.

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 context for both parameters: for status, it explains the effect of passing 'all'; for product_id, it clarifies the source (from whoami) and default behavior. This adds meaningful 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 verb 'List', the resource 'support-chat conversations in the inbox', and the default scope (open + snoozed). It differentiates from siblings like get_conversation by noting that opening a full thread is a separate tool.

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

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

The description provides clear usage context and mentions an alternative: 'open a full thread with get_conversation'. It does not explicitly state when not to use, but the context is sufficient for correct 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return order (newest first), empty list behavior, and field listing, which go 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?

Two short sentences, front-loaded with the core functionality, then usage guidance. Every sentence is valuable and concise.

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

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

Given the low complexity (1 optional param, no output schema), the description covers all needed: result structure, ordering, filtering, and relationship to update_decision.

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 for one enum parameter. Description repeats the filter options and enum values, adding no new semantic meaning 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?

Clearly states verb 'list', resource 'decisions', key fields returned (title, rationale, status, linked items), ordering (newest first), and empty list behavior. Distinguishes from update_decision by noting resolution step.

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 to resolve a decision id before using update_decision. Context is clear for a list-and-filter tool, but no explicit alternatives or when-not scenarios 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?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds: 'Read-only; empty when none match' and describes the return structure (array of experiments with fields). This provides behavioral detail beyond annotations, though it doesn't discuss pagination or rate limits. 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 fairly concise (three sentences) but could be more structured. It front-loads the main purpose and then adds details and usage guidance. No redundant phrases.

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 (list with two optional filters), the description covers purpose, return structure, parameters, and usage context. It lacks explicit enumeration of state values or pagination, but these are minor gaps. Overall sufficient 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 has 100% coverage; the description reinforces parameter meaning by noting 'from whoami' for product_id and 'e.g. running' for state. This adds context beyond the schema's brief descriptions. However, it does not enumerate all possible state 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 'List product experiments' and details the return structure (hypothesis, metric, target, state, verdict, decision). It distinguishes from sibling tools like 'create_experiment' and 'update_experiment' by emphasizing the read-only nature and specific use case (seeing what's being tested).

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: 'see what's being tested before proposing new work' and 'cite a concluded verdict as evidence when you create_task or review_artifact'. Also explains optional filters (product_id, state) and the empty result case. No contradictions with sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns empty results when none match, but otherwise doesn't reveal behavioral traits 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?

Two sentences, front-loaded with key purpose and differentiation. No wasted words; structure is efficient.

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

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

Complete for a simple list tool with good schema and annotations. Covers return behavior and parameter usage. No pagination info, but acceptable given tool simplicity.

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

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

Schema coverage is 100% with descriptions, but description adds context: q is free-text search over name+key, and product_id scopes to product from whoami. This adds meaningful detail beyond the schema alone.

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 clearly states the tool lists the product's feature catalogue with description, status, and last touched. It distinguishes itself from sibling pm_meta by noting pm_meta provides only 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?

States it's read-only and returns empty when no matches, and describes optional parameters. Provides contrast with pm_meta but doesn't explicitly exclude other alternatives or give when-not-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?

Annotations already declare readOnlyHint and idempotentHint; description adds that it returns empty when none and explains ranking and fields, providing useful context 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?

Every sentence adds value, no waste. Well-structured with clear sections for behavior, return fields, filtering, and usage hints.

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 no output schema, description fully explains return fields, filtering options, read-only nature, and relationship to other tools. Complete for a list 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 already describes both parameters (100% coverage), but description adds clarity on status enum values and optional nature, slightly improving 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?

Description clearly states it lists ideas ranked by vote count, includes details on returned fields, and distinguishes from 'insights' by explaining the difference. Very specific verb and resource.

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

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

Explicitly states read-only and suggests using this to resolve an idea ID before mutating tools. Mentions distinction from insights, but doesn't explicitly list cases when not to 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?

The description adds significant behavioral context beyond annotations: 'Read-only; empty when no merges have ever run.' and details the return structure. It confirms idempotent and non-destructive behavior consistent with annotations, with no contradictions.

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

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

The description is concise, front-loaded with the core purpose, and each sentence adds value. It efficiently states the action, return format, and usage guidance without extraneous text.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what is returned, the ordering (newest first), and how to use the output (to find event id for unmerge). No gaps.

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

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

The input schema already fully documents the single parameter (limit) with its description covering default, max, min. The tool description adds no additional parameter semantics, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the org's end-user merge history, returning an array of merge events with specific fields (id, kind, target/source user ids, reason, etc.). It distinguishes itself from sibling tools like merge_end_users and unmerge_end_users by being a read-only listing operation.

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

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

The description provides clear usage context: '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).' It implies when to use but doesn't explicitly state when not to use, though the read-only nature is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying return fields (name, status, timeframe, objective, linked-feature count) and noting 'empty when none', enhancing transparency 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?

The description is concise (three sentences), front-loads the purpose, and every sentence adds value without redundancy.

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

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

For a simple read-only list tool with good annotations and one optional parameter, the description covers purpose, hierarchy, return fields, usage workflow, and safety, leaving no gaps.

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

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

Schema coverage is 100%, and the description does not add extra meaning for the single parameter 'product_id' beyond what the schema's description already provides. 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 it lists the org's initiatives and places them in a hierarchy (goal → initiative → feature → epic → release), distinguishing from siblings like create_initiative or 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?

Explicitly advises to resolve an initiative id before using create_feature/update_feature or update_initiative, providing clear usage context. Does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations already mark it as read-only and idempotent. Description adds ordering, empty results, limit bounds, and filtering details, providing useful behavioral context 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?

Two sentences with front-loaded purpose and structured details; 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 read-only, filtered list tool with no output schema, the description covers all necessary context: ordering, empty results, limit bounds, filter parameters, and cross-references to resolve IDs.

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 descriptions, but description adds usage hints like resolving IDs via other tools and default/max limits, adding value 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 clearly states the tool searches the insight backlog, is read-only, returns results newest first, and distinguishes itself as the 'read twin of capture_insight'.

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

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

Explicitly tells when to use (survey evidence before prioritising) and how to resolve IDs via list_features and get_customer_360, differentiating from capture_insight.

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?

Description adds behavioral details beyond annotations: explains return structure (objectives with key results and progress 0..1), confirms read-only, and explains empty case. 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?

Two sentences, front-loaded with purpose, then usage guidance. Every sentence adds value; no wasted words.

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

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

Given no output schema, description fully explains what the tool returns and how to use it. For a simple list tool with one optional param, all needed context is provided.

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

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

Schema has 100% coverage for one parameter; description adds value by noting the source ('from whoami') and that it's optional, beyond the schema's own description.

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

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

Clearly states 'List the org's OKRs' with specific verb and resource. Distinguishes from sibling tools like create_objective and update_objective by focusing on reading objectives for prioritization.

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 'Read it before prioritising' and advises to tie tasks to objectives and cite progress. No when-not or alternatives mentioned, but usage context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds 'cheap to scan' and 'empty when none exist', which are helpful but not critical.

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

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

Two sentences: first states purpose and return, second gives usage guidance. No waste, front-loaded.

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

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

For a simple list tool with 1 optional param, no output schema, the description fully covers purpose, return format, and usage 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 covers product_id with description. Tool description reinforces 'optional, from whoami'. Since schema coverage is 100%, baseline 3, but adds value with usage hint.

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?

Clearly states verb 'List', resource 'Pages', and context 'on the spine'. Distinguishes from get_page (full content) and review_artifact (critique).

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 use for finding page ID then call get_page, and pair with review_artifact. Mentions optional product_id from whoami.

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 beyond annotations: 'Read-only' confirms readOnlyHint, 'empty when nothing has shipped' explains edge case, 'newest first' details ordering. 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?

Four concise sentences front-load purpose and return structure, then provide usage guidance and parameter hint. 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 list tool with one optional param and no output schema, description covers return format, ordering, edge case, usage scenarios, sibling relationship, and parameter source. Fully adequate.

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

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

Schema coverage is 100% and description repeats 'Optional product_id, from whoami', adding no new meaning beyond schema description. 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?

Clearly states 'List shipped releases' and describes return structure (array, newest first, with version/changelog/ship date). Distinguishes from siblings like create_release and get_roadmap_drift through usage context.

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

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

Explicitly tells when to use: to answer 'what did we ship recently?', ground changelogs, and before reading get_roadmap_drift. Provides explicit scenario and sibling reference.

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 provide readOnlyHint, idempotentHint, destructiveHint. Description reinforces read-only and adds 'returns empty when none exist' and 'newest first'. No contradictions, but adds only moderate extra 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 informative sentences, no fluff. Purpose is front-loaded. 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?

Simple tool with one optional param and no output schema. Description covers what is returned, sorting, use case, and optional filter. Sufficient for effective use. Could hint at project scope but not necessary.

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?

Single optional parameter 'state' is described in schema and repeated in description ('Optional state filter (e.g. 'active')'). Schema coverage is 100%, so baseline 3. No additional meaning added.

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 clearly states the tool lists sprints with specific fields (name, goal, state, window) sorted newest first, and is read-only. It distinguishes from sibling tools like create_sprint and update_sprint by explicitly being a read-only listing.

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: use to see delivery cadence and resolve sprint_id before scheduling tasks via create_task/update_task. Mentions optional state filter. Lacks explicit when-not-to-use alternatives, but the context is sufficient.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false; description adds 'Read-only; returns an empty list when nothing matches,' providing behavioral consistency and detail 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?

Three concise sentences: main action, optional filters, usage advice. Front-loaded, no fluff, every sentence adds value.

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

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

Despite no output schema, description lists return fields (status, priority, assignees, linked items) and empty-list behavior. Sufficient for a simple 2-param 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%; description adds meaning by explaining the parameters' purpose (narrow by list/status) and directing to pm_meta for ID resolution, enhancing 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 clearly states the tool lists board tasks with specific fields (status, priority, assignees, linked items). It distinguishes from siblings like 'get_task' (single task) and mutation 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?

Explicitly advises using it to find a task ID before get_task, update_task, or comment_on_task. Suggests resolving IDs via pm_meta, providing clear when-to-use and 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?

Discloses effects beyond annotations: writes are performed, FK rows are re-pointed, sources are tombstoned, and the operation is reversible for 30 days. Annotations are destHint=false, etc., but the description adds meaningful context 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?

Single paragraph front-loaded with the main action and result. Every sentence adds value: what the tool does, how IDs come from candidates, reversibility, and required params. No wasted words.

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

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

Given no output schema, the description mentions return includes merge event id and references list_identity_merges for later recovery. Covers all key aspects: inputs, effects, reversibility, and prerequisites. Could specify return format more but sufficient for a write 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 descriptions for all three parameters. The description reinforces that 'target_end_user_id' and 'source_end_user_ids' are required and links them to get_device_candidates. Adds minor value beyond schema by clarifying that source IDs are UUIDs from candidates.

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'), specifies the resource ('end-users'), and mentions the outcome ('return the merge result, including the merge event id'). It distinguishes from sibling tools like 'unmerge_end_users' and 'get_device_candidates'.

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.' Also notes the operation is reversible via 'unmerge_end_users' and that required parameters are both given. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by stating 'Read-only; returns arrays for resolution only' and clarifying that list_features is richer. No contradictions with annotations.

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

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

The description is three sentences with no waste. The first sentence states the main action, the second provides behavioral context, and the third gives usage guidance. Front-loaded and efficient.

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

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

Given no output schema, the description explains the return format (arrays of id+name pairs) and the purpose. It notes that list_features is richer, which helps the agent choose. Minor omission: it could specify that it returns all PM metadata in one call, but the information is 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?

The tool has no parameters, so baseline is 4. The description does not need to add parameter details, and it mentions the output format (id+name pairs) which is useful.

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 the org's PM lists, statuses, members, and features as id+name pairs. It distinguishes itself from list_features by noting that list_features carries the richer catalogue. The verb 'list' and the specific resources are unambiguous.

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

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

Explicitly states when to use the tool: 'Call it to turn a name into an id before create_task / update_task — never guess an id.' It also clarifies its limited scope compared to list_features, providing a clear when-not-to-use alternative.

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

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

Annotations indicate it's not read-only, not idempotent, etc. The description adds that the message 'appears live for teammates and is org-visible', and that it returns the posted message. This context is 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 three sentences: first sentence states main action and return, second adds visibility and appropriateness, third specifies requirements. No waste, front-loaded with key info.

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 two required parameters, no output schema, and no annotations beyond safety flags, the description covers prerequisites, membership constraint, return value, and visibility. It omits error handling or rate limits but is adequate for a straightforward posting 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% and both parameters are described clearly in the schema. The description reiterates the necessity of both parameters and sources channel_id from list_channels, but adds minimal 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 uses specific verb 'post' and resource 'message to a team Comms channel'. It distinguishes from siblings like 'reply_in_channel' by mentioning 'post' and 'channel you belong to'. Clear and 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 a prerequisite (resolve channel_id via list_channels) and a limitation (only channels you're a member of). It also advises 'keep it work-relevant'. However, it does not explicitly state when not to use this tool versus alternatives like reply_in_channel.

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 claims the tool is idempotent ('Idempotent — an already-promoted idea returns its existing feature'), but the annotation 'idempotentHint' is false, which directly contradicts the description. This is a serious inconsistency that misleads the agent.

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 (four sentences) with no redundant information. It front-loads the main purpose and idempotency, then gives usage tips. Every sentence earns its place.

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

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

Given no output schema, the description states it returns the feature id. It explains idempotency, the prerequisite (list_ideas), and a post-step (update_feature). It is complete for a tool of this complexity, though missing details about error cases.

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

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

The input schema covers 100% of parameters with descriptions. The description adds value by providing sources for parameter values ('from list_ideas' for id, 'from whoami' for product_id) and explaining that product_id is optional with a default behavior. This goes 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 'promote' and the resource 'idea to feature'. It details the action: creates a feature, stamps the idea, links them, and returns the feature id. This distinguishes it from siblings like 'create_feature' (which creates from scratch) and '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?

The description explains how to use the tool: resolve the id via 'list_ideas', only id is required, and suggests aligning the new feature to an initiative afterwards with 'update_feature'. It does not explicitly state when not to use it, but provides clear context and prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it 'returns the messages, empty when the channel is silent,' which is useful but not extensive. 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?

Two clear sentences, front-loaded with the main action. Every sentence adds value with 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?

Despite no output schema, the description explains what is returned and when it might be empty. Given good annotations and simple input, it is comprehensive enough for an agent to use 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 descriptions for both parameters. The description reinforces that channel_id comes from list_channels and that limit is optional, but adds no new 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 verb 'read', the resource 'Comms channel's recent messages', and includes constraints (must be a member). It distinguishes from sibling tools like list_channels by instructing to resolve channel_id first.

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 prerequisite: 'Resolve channel_id first with list_channels — never guess it.' Indicates it is read-only, giving clear context. Does not explicitly state when not to use, but the guidance is strong.

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

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

Annotations are minimal (no readOnly, destructive, etc.), so description carries burden. It discloses that the reply is posted as the connected member, is org-visible, and returns the posted reply. This adds transparency about visibility and return value.

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 that cover purpose, return, visibility, and parameter guidance. No wasted words. Front-loaded with the key action.

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

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

Covers all essential aspects: required parameters, resolution steps, return value, visibility. With 3 params and no output schema, it is sufficiently complete. Does not mention error handling, but that is acceptable for a 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?

Schema coverage is 100%, so baseline is 3. The description adds value by specifying how to obtain channel_id and parent_id (via list_channels and read_channel), which is critical context beyond the schema descriptions.

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

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

The description clearly states the action (reply in a thread), the resource (specific message in a channel), and the context (as connected member). It distinguishes from siblings like post_to_channel and reply_to_conversation by specifying threading and channel membership.

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

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

Explicitly tells the agent to resolve channel_id via list_channels and parent_id via read_channel, providing clear prerequisites. Does not explicitly exclude alternatives, but the context makes it clear when to use (replying to a thread) vs posting new messages or replying to DMs.

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 indicate readOnlyHint=false and destructiveHint=false; description adds that it is a write operation, goes to the end-user on the conversation's channel, and is sent as the connected member. Adds useful context 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?

Three sentences: first states purpose and effect, second gives prerequisites, third differentiates from siblings and mentions required params. No wasted words, front-loaded.

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

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

For a tool with 2 params, no output schema, and minimal annotations, the description covers purpose, usage guidelines, prerequisites, alternatives, and required params. Complete for effective use.

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

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

Input schema has 100% description coverage, but description adds practical context: conversation_id should come from list_conversations, and body is required. The example schema provides a concrete usage pattern.

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

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

The description clearly states it sends a public reply to a support-inbox conversation as the connected member, and distinguishes from siblings by mentioning add_note and resolve_conversation.

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 provides when to use (public reply), when not to (use add_note for internal notes, resolve_conversation to close), and prerequisites (resolve conversation_id via list_conversations, read thread with get_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 declare readOnlyHint=false (write) and idempotentHint=true (idempotent). The description adds that it notifies the invitee, providing valuable behavioral context beyond 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?

Two sentences: first states purpose and effect, second gives prerequisite and requirement. Front-loaded, 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?

Covers purpose, parameters, prerequisite, and side effect (notification). Without output schema, describing the return result would improve completeness, but current level is sufficient for agent use.

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

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

Schema has 100% coverage with clear descriptions. Description adds context: booking_id comes from list_bookings, and start is ISO 8601. This supplements the schema meaningfully.

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

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

The description clearly states the verb 'Reschedule' and resource 'booking', specifies the new start time format (ISO 8601), and notes that the invitee is notified. It distinguishes itself 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?

Explicitly instructs to resolve booking_id via list_bookings first, preventing misuse. It also notes that both booking_id and start are required, guiding correct invocation.

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 idempotentHint=true and destructiveHint=false. Description adds that it's a write operation and returns a result, but does not significantly extend behavioral understanding 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?

Two concise sentences clearly communicating purpose, effect, and usage guidance with no redundant 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 idempotent write tool with one parameter and no output schema, the description is mostly complete but lacks detail on what the returned result contains, which could assist the agent in processing the response.

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

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

Schema coverage is 100% with a clear description for the single parameter. Tool description repeats the prerequisite of list_conversations but does not add 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?

Clearly states the verb 'Mark' and resource 'support-inbox conversation resolved (closed)', with outcome 'return the result'. Distinguishes from sibling tools like get_conversation (read) and reply_to_conversation (different 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?

Explicitly says to use after replying and handling the ask, and to first get the conversation_id via list_conversations. Provides clear when-to-use and prerequisite, helping select among 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?

Beyond annotations, the description explains that the operation is a write, not idempotent, and details the state changes: current version becomes 'reverted' (kept for learning signal) and the chosen version becomes current. This adds valuable behavioral context that annotations alone do not provide.

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

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

The description is concise, front-loaded with the action, and every sentence adds value. It efficiently covers purpose, behavior, and parameter usage without repetition.

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

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

Given the tool's simplicity (2 params, no output schema), the description adequately covers all aspects: purpose, behavior, parameter guidance, and side effects. No gaps remain for an agent to misuse 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. The description adds extra guidance: 'never guess it' and emphasizes that version_id must come from list_artifact_versions. This provides additional clarity beyond the schema description.

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

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

The description clearly states the verb 'Restore' and the resource 'artifact version', and distinguishes from sibling tool list_artifact_versions by specifying the source of version_id.

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

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

The description provides clear context on when to use: after obtaining version_id from list_artifact_versions, and never guessing it. However, it does not explicitly state when not to use it or compare with 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?

The description discloses that the tool is a write operation (each call reruns review and persists a new version), consistent with readOnlyHint=false. It adds that it is a 'small LLM call,' which gives cost context. This goes beyond the annotations, which only provide hints without detail.

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

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

The description is front-loaded with the core purpose and criteria in the first sentence. It then provides behavioral details and parameter guidance. While it is dense, nearly every sentence earns its place; a slight reduction in wordiness would improve conciseness.

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

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

Given no output schema, the description adequately explains the return structure (section, severity, suggested fix, evidence quote, score 0-100) and mentions persisting as a new version (linking to list_artifact_versions). It fully covers the tool's purpose, usage, parameters, 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%. The description adds meaning by explaining that target_id comes from specific list tools, that target_type enum corresponds to artifact kinds, and that rubric_id can be omitted to use the default. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's role as an agent-as-critic over draft artifacts (feature spec, experiment plan, page) with specific criteria (problem/hypothesis, success metric, evidence, risks, plan) and output structure (findings and score). This distinguishes it from sibling tools which do not perform reviews.

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 the tool before sending a draft for sign-off and instructs the agent to resolve target_id via other tools (pm_meta, list_features, etc.). It also notes that each call persists a new version. It lacks explicit when-not-to-use or alternative tools, but the advice is clear enough.

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

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

Annotations provide idempotentHint=true, and description reinforces 'Safe to retry — a second undo changes nothing (fails with already_reverted)'. Also explains 'un-tombstoning' sources, adding behavioral detail beyond 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?

Three sentences, front-loaded with action, no wasted words. Clearly structured with mechanism, idempotency note, and usage instruction.

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

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

Covers purpose, mechanism, idempotency, and parameter source. Lacks description of return value, but given no output schema and practical nature of the tool, this is a minor gap. Overall sufficient 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% for the single parameter event_id. Description adds reference to list_identity_merges but does not add meaning beyond the schema. 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?

Description clearly states 'Undo a previous end-user merge' with specific verb and resource. It details the mechanism (reads merge ledger, re-points FK rows, un-tombstones sources) and distinguishes it from sibling 'merge_end_users'.

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

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

Provides clear context: 'Use to correct a wrong identity merge' and instructs to find event_id via list_identity_merges. Mentions 30-day reversibility. Does not explicitly state when not to use, but context is sufficient for correct 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 indicate mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds behavioral details: the effect of moving status to 'decided' re-stamps decision time, and linking is verified in-org. No contradiction with annotations. It doesn't cover authorization or rate limits, but annotations already provide 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 concise sentences, front-loaded with the core action and partial update behavior. Each sentence is informative without extraneous words. No redundancy with the schema or 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?

Given the tool complexity (6 parameters, 1 required, 2 enums) and no output schema, the description covers key aspects: how to get the id, the behavior on status change, and linking instructions. It doesn't explain the return value in detail, but 'return it' implies the updated object is returned. The schema and annotations already cover most structural info, so the description fills gaps well.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains how to obtain the id (via list_decisions), the effect of status changes on decision time, and the semantics of link_type+link_id (verified in-org, clear with nulls). For title and rationale, it adds 'null clears it', which for rationale is already in schema but for title it's new. Overall, it adds significant value.

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

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

The description clearly states 'Update a decision and return it; omitted fields unchanged.' This specifies the action (update), the resource (decision), and the behavior (partial update). It distinguishes from sibling tools like create_decision or list_decisions by describing the update semantics.

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 when-to-use guidance: for updating decisions, with specific notes on status (re-stamps decision time on 'decided'), re-linking via link_type+link_id (verified in-org), and clearing with nulls. It also advises to resolve the id via list_decisions. However, it doesn't explicitly state when not to use this tool, but the context is clear enough.