Server Quality Checklist

Tool Scores

• get_ideaB
  3.1/5.0
  Behavior2/5

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

  Annotations indicate openWorldHint=true (external access possible) and readOnlyHint=true, but the description adds minimal context beyond 'detailed information'. Fails to address error cases (e.g., invalid ID), cache behavior, or implications of openWorldHint.

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

  Conciseness5/5

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

  Single sentence with front-loaded verb. No redundant words or unnecessary elaboration. Appropriate length for tool complexity.

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

  Completeness3/5

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

  Adequate for a simple single-parameter read operation with full schema coverage and safety annotations, but lacks completeness regarding error handling and sibling tool relationships that would assist agent selection.

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

  Parameters3/5

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

  Schema coverage is 100% with the ideaId parameter fully documented. The description references 'by ID' which aligns with the parameter, but adds no semantic depth regarding ID format or constraints beyond the schema definition.

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

  Purpose4/5

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

  States specific verb (Get) and resource (idea), and implies distinction from siblings like list_ideas/search_ideas via 'by ID' phrasing. However, it does not explicitly contrast with the multiple sibling search/list tools.

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

  Usage Guidelines2/5

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

  Provides no guidance on when to use this tool versus the available alternatives (list_ideas, query_ideas, search_ideas). Does not indicate prerequisites like needing to obtain the ID first.

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

• get_signal_analyticsB
  3.2/5.0
  Behavior3/5

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

  Annotations establish the read-only, non-destructive safety profile. The description adds that the operation is temporal ('over a time period') and involves aggregation, but it omits what specific metrics are returned (counts, averages, sentiment scores) or any rate limiting behavior, leaving significant behavioral gaps.

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

  Conciseness4/5

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

  The single sentence is efficiently structured with a front-loaded verb ('Get') and zero redundancy. However, the extreme brevity limits the description's utility given the absence of an output schema.

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

  Completeness3/5

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

  Sufficient for a simple read-only tool with well-documented input parameters and safety annotations. However, lacking an output schema, the description should ideally specify what analytics structure is returned (e.g., counts, trends) rather than relying solely on the generic term 'analytics'.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is adequately met. The description mentions 'aggregated' which contextually supports the 'groupBy' parameter's purpose, but it adds no additional semantic detail regarding date format expectations or aggregation logic beyond what the schema already documents.

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

  Purpose4/5

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

  The description uses 'aggregated analytics' to clearly identify the operation (aggregation/statistics) and resource (signals), distinguishing it from the sibling tool 'list_signals' which presumably returns individual signal records rather than rollups. The temporal scope ('over a time period') further clarifies the analysis context.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to select this tool versus 'list_signals' for raw data retrieval, nor does it mention the intended use case (e.g., reporting, trend analysis) or prerequisite conditions for the date range.

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

• list_ideasB
  3.2/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, covering safety profile. Description adds 'Returns paginated results' which discloses pagination behavior not present in annotations. However, lacks details on pagination mechanics (cursor vs offset), rate limits, or maximum dataset sizes that would help an agent handle the response correctly.

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

  Conciseness4/5

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

  Two sentences efficiently structured—first establishes scope and capability, second discloses return format. No tautology or redundant phrasing. Could benefit from one additional sentence distinguishing from siblings or explaining pagination defaults, but currently wastes no space.

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

  Completeness3/5

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

  With 100% schema coverage and clear annotations, minimal description burden for parameters. However, lacking output schema means the description should ideally explain return structure; 'paginated results' is minimal. Critical gap is missing distinction from query_ideas and search_ideas siblings, which could cause selection errors.

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

  Parameters3/5

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

  Schema description coverage is 100% with clear enum values and descriptions for all 5 parameters. Description mentions 'optional filters' generally but does not add semantic meaning beyond the schema (e.g., explaining relationships between source/destination or typical usage patterns). Baseline 3 appropriate given high schema coverage.

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

  Purpose4/5

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

  Clearly states 'List ideas in the workspace' with specific resource (ideas) and action (list). Mentions 'optional filters' indicating filtering capability. However, fails to distinguish from siblings like get_idea (singular fetch), query_ideas, or search_ideas which appear to serve similar purposes.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this tool versus alternatives like get_idea, query_ideas, or search_ideas. Does not mention prerequisites or when-not-to-use conditions. The phrase 'optional filters' implies usage context but does not contrast with other list/query tools.

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

• update_ideaB
  3.2/5.0
  Behavior3/5

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

  Annotations already cover mutation (readOnlyHint=false) and external world (openWorldHint=true). The description adds context by grouping the four RICE parameters under 'scores', but does not clarify partial update semantics, non-destructive nature, or what the destination field implies.

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

  Conciseness4/5

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

  Two concise sentences with front-loaded action. The 'etc.' placeholder prevents a perfect score as it wastes opportunity to mention critical parameters like 'destination' or partial update capability.

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

  Completeness3/5

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

  Adequate for identifying the tool's basic function but incomplete for a 9-parameter mutation tool with external integrations. Missing: partial update semantics, the significance of the destination enum (GitHub, Linear, etc.), and differentiation from normalize_idea.

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

  Parameters3/5

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

  Schema has 100% description coverage, establishing a baseline of 3. The description adds semantic value by conceptually grouping riceReach, riceImpact, riceConfidence, and riceEffort as 'scores', but completely omits mention of the 'destination' parameter despite its significance for external integrations.

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

  Purpose4/5

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

  States specific verb (Update) and resource (idea) and lists key updatable fields (title, summary, status, scores). However, it fails to distinguish from sibling 'normalize_idea' which could also modify ideas, and uses vague 'etc.' rather than mentioning the destination integration capability.

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

  Usage Guidelines2/5

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

  Provides no guidance on when to use this tool versus alternatives like 'normalize_idea' or 'create_ticket'. Does not mention prerequisites (e.g., needing an ideaId from get_idea) or that partial updates are supported since only ideaId is required.

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

• get_decision_historyB
  3.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds 'audit trail' implying immutable historical records, and 'complete' suggesting no filtering. However, it omits pagination behavior, chronological ordering, or whether this includes system-generated vs user-logged decisions despite openWorldHint=true.

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

  Conciseness5/5

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

  Single sentence, front-loaded with active verb, zero redundancy. Appropriate length for a simple single-parameter read operation.

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

  Completeness3/5

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

  Minimally sufficient for a low-complexity read tool with rich annotations. However, gaps remain: 'complete' is undefined (time range? all decision types?), and without output schema, some hint about returned structure (array of decisions?) would improve invocation confidence.

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

  Parameters3/5

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

  Schema coverage is 100% with ideaId fully documented. Description mentions 'for an idea' which aligns with the parameter but adds no additional semantic constraints (e.g., UUID format, validation rules) or usage context beyond the schema.

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

  Purpose4/5

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

  Clear verb 'Get' with specific resource 'decision history (audit trail)' and scope 'complete...for an idea'. The parenthetical clarification distinguishes this from generic idea retrieval, though it doesn't explicitly differentiate from sibling get_idea.

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

  Usage Guidelines2/5

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

  No guidance on when to use this versus get_idea (current state) or log_decision (writing decisions). No mention of prerequisites like idea existence or permissions needed to view audit trails.

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

• list_relationshipsB
  3.3/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by clarifying the bidirectional lookup scope (source and target), but does not address openWorldHint=true or explain return format/pagination.

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

  Conciseness5/5

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

  Single sentence efficiently conveys purpose and scope. The parenthetical placement puts critical behavioral detail (bidirectional) immediately after the main clause without verbosity. No wasted words.

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

  Completeness3/5

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

  Adequate for a simple read operation with complete parameter documentation and safety annotations. However, lacks output specification (format of returned relationships) and pagination behavior, which would be helpful given no output schema exists.

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

  Parameters3/5

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

  Schema coverage is 100% with the ideaId parameter fully documented. The description implies the parameter by referencing 'an idea' but does not add semantic details (format, constraints) beyond what the schema provides, meeting the baseline for high-coverage schemas.

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

  Purpose4/5

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

  States specific verb 'Get' and resource 'relationships'. The parenthetical '(both as source and target)' clearly distinguishes the scope of retrieval (bidirectional), differentiating it from potentially unidirectional alternatives.

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

  Usage Guidelines2/5

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

  Provides no explicit guidance on when to use this tool versus siblings like create_relationship or get_idea. The 'both as source and target' hints at behavior but doesn't constitute usage guidelines.

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

• list_signalsB
  3.3/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, covering safety profile. Description adds valuable context about what constitutes signals (external feedback examples) but omits behavioral details like pagination behavior, rate limits, or default sorting. 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.

  Conciseness5/5

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

  Single well-structured sentence with zero waste. Front-loaded with verb and resource ('List signals'), immediately clarifies domain with examples in parentheses, and ends with capability note ('with optional filters').

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

  Completeness3/5

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

  Adequate for a 6-parameter read-only list operation with robust schema coverage and annotations present. However, lacking output schema, the description omits what the tool returns (e.g., array of signal objects) and pagination behavior details that would complete the picture.

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

  Parameters3/5

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

  Schema description coverage is 100%, so baseline is 3. Description mentions 'optional filters' generally corresponding to the filter parameters (ideaId, source, sentiment, category) but does not add semantic details, validation rules, or format specifics beyond what the schema already provides.

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

  Purpose4/5

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

  Clear verb 'List' + resource 'signals' with helpful parenthetical examples distinguishing what signals are (Twitter, Reddit, support tickets). Implicitly distinguishes from sibling 'get_signal_analytics' (list vs. analytics) and 'attach_signal' (retrieval vs. attachment), though explicit sibling differentiation would strengthen it.

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

  Usage Guidelines2/5

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

  States 'with optional filters' implying filter capability exists, but provides no explicit guidance on when to use this tool versus alternatives like 'get_signal_analytics' or when filtering is necessary versus fetching all signals.

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

• search_ideasB
  3.3/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, establishing safety. Description adds that search targets 'title and summary fields' (internal scope not obvious from name). However, fails to clarify openWorldHint=true implications (varying results/external data) or describe output format/pagination behavior.

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

  Conciseness5/5

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

  Extremely concise two-sentence structure with zero redundancy. First sentence states purpose, second specifies search scope. Appropriate length for the tool's complexity.

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

  Completeness3/5

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

  Adequate for a simple search tool with excellent schema coverage and safety annotations, but lacks output value description (no output schema exists) and misses opportunity to differentiate from similar sibling tools (query_ideas vs search_ideas).

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

  Parameters3/5

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

  Schema coverage is 100% with complete descriptions for all 4 parameters. Description mentions 'text query' reinforcing the query parameter's purpose and specifies searched fields, but does not add semantic details beyond what the schema already provides for status, source, or limit.

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

  Purpose4/5

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

  Clear verb (search) and resource (ideas). Specifies scope by mentioning 'title and summary fields' as search targets. However, does not explicitly distinguish from siblings like 'query_ideas' or 'list_ideas' which likely perform similar operations.

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

  Usage Guidelines2/5

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

  No guidance provided on when to use this tool versus alternatives like list_ideas, query_ideas, or get_idea. No mention of required authentication from check_auth or prerequisites.

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

• query_ideasA
  3.5/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context through examples showing the system's ability to interpret complex natural language filters (RICE scores, Slack sources), which aligns with the openWorldHint. However, it omits details about result limits, pagination, or ambiguity handling.

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

  Conciseness5/5

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

  Front-loaded purpose statement ('Execute a natural language query...') followed immediately by a bulleted example list. No wasted words; structure efficiently communicates both capability and input patterns in minimal space.

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

  Completeness4/5

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

  Adequate for a single-parameter read operation. Examples compensate for lack of output schema by demonstrating expected query complexity. Annotations cover safety profile. Minor gap: no mention of result format or volume limitations.

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

  Parameters4/5

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

  With 100% schema coverage, the baseline is 3. The description significantly exceeds this by providing five diverse examples that illustrate the parameter's semantic range—showing it accepts aggregations ('top 5'), temporal filters ('this month'), source filtering ('Slack'), and scoring metrics ('RICE scores').

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

  Purpose4/5

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

  States specific action (Execute) and resource (natural language query about ideas). Examples clarify scope (filtering by impact, scores, timeframe). However, it does not explicitly distinguish from sibling 'search_ideas' or 'list_ideas', which likely perform similar retrieval with structured parameters.

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

  Usage Guidelines2/5

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

  Provides five concrete input examples but offers no explicit guidance on when to use this tool versus structured alternatives like 'search_ideas', 'list_ideas', or 'get_idea'. No prerequisites, error conditions, or exclusions are mentioned.

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

• attach_signalA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare this is a non-read-only (write), non-destructive operation with external world interaction. The description adds domain context by clarifying that signals represent 'external feedback', adding semantic meaning beyond the structured annotations. It does not address idempotency, conflicts, or side effects, but meets the lowered bar for annotated tools.

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

  Conciseness5/5

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

  The description consists of two efficient sentences: the first states the action, the second provides domain context. No redundancy or filler content exists. Every sentence earns its place by conveying distinct information (mechanism vs. domain meaning).

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

  Completeness4/5

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

  Given the tool's simplicity (2 flat required parameters, 100% schema coverage, no output schema), the description is appropriately complete. It explains the relationship being created (feedback-to-idea association). Annotations handle the safety profile (non-destructive write), so the description need not repeat this. Could mention error conditions (e.g., if IDs don't exist) for a 5.

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

  Parameters3/5

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

  Input schema has 100% description coverage with clear parameter definitions ('The ID of the signal to attach', 'The ID of the idea to attach the signal to'). The description reinforces the parameter concepts by mentioning 'signal' and 'idea' but does not add syntactic details or format constraints beyond what the schema provides. Baseline score 3 applies per rubric for high schema coverage.

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

  Purpose4/5

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

  The description uses specific verbs ('Link', 'associates') and resources ('signal', 'idea'). It clarifies domain semantics by defining signals as 'external feedback' and ideas as 'product ideas'. However, it does not explicitly distinguish from sibling tool 'create_relationship', which also creates associations between entities.

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

  Usage Guidelines3/5

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

  The description implies usage through domain context ('external feedback with a specific product idea'), suggesting when you have customer feedback to attach to an idea. However, it lacks explicit when-to-use guidance, prerequisites (e.g., requiring both signal and idea to exist first), or comparison to alternatives like create_relationship.

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

• create_ideaA
  4/5.0
  Behavior4/5

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

  Adds valuable context beyond annotations: specifically mentions plan limit validation behavior that could cause invocation failure. Annotations already indicate non-destructive write (readOnlyHint:false, destructiveHint:false), so description's contribution of the plan limits check is meaningful additional context.

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

  Conciseness5/5

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

  Two efficient sentences with zero waste. Front-loaded with action verb. Second sentence earns its place by conveying critical operational behavior (plan limit validation) that affects invocation success.

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

  Completeness4/5

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

  Adequate for a creation tool with 6 parameters. Plan limits mention satisfies critical behavioral disclosure. No output schema exists, so absence of return value description is acceptable. Could strengthen by describing failure behavior when limits exceeded, but sufficient for complexity level.

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

  Parameters3/5

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

  Schema coverage is 100% with all 6 parameters well-documented. Description mentions no specific parameters, but with complete schema coverage, baseline 3 is appropriate—description doesn't need to compensate for documentation gaps or add redundant parameter details.

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

  Purpose5/5

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

  Specific verb 'Create' with clear resource 'idea' and scope 'in the workspace'. Effectively distinguishes from siblings: contrasts with get_idea/list_ideas/query_ideas (read operations), update_idea (modification), and create_ticket/create_relationship (different resource types).

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

  Usage Guidelines3/5

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

  Mentions 'Checks plan limits before creating' which implies a usage constraint, but lacks explicit when-to-use guidance (e.g., when to prefer create_idea vs normalize_idea) or alternative recommendations. Usage is implied rather than explicit.

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

• log_decisionA
  4.2/5.0
  Behavior3/5

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

  Annotations declare readOnly=false and destructive=false. Description adds 'creates an audit trail entry' which clarifies the non-destructive write behavior. Does not elaborate on auth requirements, rate limits, or side effects 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.

  Conciseness4/5

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

  Well-structured with clear sections for event types and closure categories. Front-loaded with purpose statement. Lengthy enum lists are justified by complexity, though could be slightly more concise.

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

  Completeness4/5

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

  Comprehensive coverage of 15 event types and 12 closure categories with semantic context appropriate for this complexity. No output schema present; description correctly focuses on input semantics and audit purpose.

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

  Parameters5/5

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

  Despite 100% schema coverage, description adds substantial value by categorizing enum values (e.g., 'accepted, rejected: Decision outcomes', 'shipped, merged: Positive closures'), explaining semantic groupings that raw schema cannot express.

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

  Purpose5/5

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

  Clear specific verb 'Log' + resource 'decision event' + scope 'for an idea'. Distinguishes from siblings like create_idea (creates the idea itself) and get_decision_history (retrieves rather than writes).

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

  Usage Guidelines4/5

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

  Extensive taxonomy of event types (lifecycle vs outcomes vs closures) and closure categories (positive vs deferrals vs rejections) provides clear implied usage guidance. Notes closure categories are 'required for some events'. Lacks explicit 'when not to use' or named alternatives.

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

• create_relationshipA
  4.3/5.0
  Behavior4/5

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

  Annotations indicate mutability (readOnlyHint=false) and safety (destructiveHint=false). Description adds crucial behavioral detail: directionality (bidirectional vs directional) for each relationship type. Minor gap: doesn't disclose idempotency behavior or conflict resolution when relationships already exist.

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

  Conciseness5/5

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

  Front-loaded with clear action statement, followed by structured bullet list. Every line earns its place: no redundancy with schema, zero filler. Efficient scannable format.

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

  Completeness4/5

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

  Appropriately complete for a 4-parameter mutation tool with full schema coverage and openWorldHint. Covers domain logic (relationship ontologies) thoroughly. Minor deduction for missing idempotency/duplicate-handling disclosure expected in a relationship creation API.

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

  Parameters5/5

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

  Despite 100% schema coverage (baseline 3), description massively enhances value by elaborating all 7 enum values for relationshipType with semantic definitions ('General relationship', 'solves the same problem differently', etc.) and directionality constraints—critical context not present in schema.

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

  Purpose5/5

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

  Specific verb 'Create' + resource 'relationship' + scope 'between two ideas' clearly identifies the tool's function. Distinct from siblings like create_idea (creates nodes) and attach_signal (attaches metadata).

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

  Usage Guidelines3/5

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

  Provides detailed domain guidance via relationship type definitions (bidirectional vs directional), but lacks explicit tool-selection guidance—no mention of when to use this vs siblings like attach_signal or when to prefer list_relationships for reading existing links.

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

• normalize_ideaA
  4.3/5.0
  Behavior4/5

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

  While annotations indicate non-destructive mutation (readOnly=false, destructive=false) and external interaction (openWorld=true), the description adds valuable behavioral context: it discloses the judgment/verdict mechanism (READY/ALMOST READY/NOT READY), signal analysis outputs, and the guarantee that output 'ALWAYS ends with a commit decision' with specific external destinations (GitHub, Jira, Linear).

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

  Conciseness4/5

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

  Though lengthy, the description is well-structured with clear functional sections (purpose, usage triggers, proactive guidance, output specification). Minor inefficiency exists with poetic/marketing phrases ('This is the moment where thinking stops', 'IdeaLift'), but overall every section serves the agent's understanding.

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

  Completeness4/5

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

  Despite lacking a formal output schema, the description comprehensively details the return structure through explicit enumeration: Readiness Verdict, Signal Analysis, Structured spec, and Commit options. This adequately compensates for the missing output schema in a complex multi-step tool.

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

  Parameters3/5

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

  With 50% schema description coverage, the description partially compensates by contextualizing the types of input (meeting notes, Slack threads, feature requests) that map to the 'text' parameter. However, it fails to mention the 'context' parameter or its 'source' enum entirely, leaving that parameter undocumented beyond the schema.

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

  Purpose5/5

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

  The description clearly states the specific action ('Transform raw ideas into execution-ready work items') and distinguishes this from sibling tools like create_idea or update_idea by positioning it as a 'COMMIT LAYER' that judges readiness and bridges thinking to execution.

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

  Usage Guidelines5/5

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

  Contains an explicit 'USE this tool when' section with specific intent signals (e.g., 'We should...', 'Feature request:', 'normalize', 'make this backlog-ready') and instructs the agent to 'PROACTIVELY offer' usage when these signals are detected, providing clear guidance on when versus alternatives.

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

• connect_destinationA
  4.4/5.0
  Behavior4/5

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

  Annotations establish read-only/non-destructive safety. Description adds crucial UX context: returns an authorization link (not immediate connection), requires user click-through, and provides time estimate (~30 seconds). Explains the indirect nature of the connection flow.

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

  Conciseness5/5

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

  Perfectly structured with clear sections: purpose declaration, positive conditions, negative conditions, and return behavior. Every sentence earns its place; no redundancy while covering all necessary guidance.

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

  Completeness4/5

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

  For a single-parameter tool with complete schema and no output schema, the description fully explains the return behavior (authorization link) and user experience (click to authorize, ~30s duration). Could optionally mention error handling for invalid destinations, but adequately complete.

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

  Parameters3/5

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

  Schema has 100% coverage with clear enum values (github, jira, linear) and description 'Which service to connect'. Description mentions the specific services in prose, reinforcing the schema but not adding distinct validation rules or format details beyond the structured definition.

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

  Purpose5/5

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

  Specific verb 'Connect' paired with resource 'ticket destination' and explicit examples (GitHub, Jira, Linear). Clearly distinguishes from sibling 'list_destinations' (which only lists) and 'create_ticket' (which creates tickets within destinations).

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

  Usage Guidelines5/5

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

  Exceptional explicit guidance with 'USE this tool when' and 'DO NOT use this tool when' sections. Names specific sibling 'list_destinations' as the correct alternative for exploration queries, creating clear decision boundaries for the agent.

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

• create_ticketA
  4.4/5.0
  Behavior4/5

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

  Annotations indicate write-operation (readOnlyHint:false) and external system impact (openWorldHint:true). The description adds valuable context: it confirms creation of 'REAL' external tickets, implies duplicate detection exists (via the 'force' parameter mentioning 'Skip duplicate check'), and describes post-commit behavior (returns URL, ID, confirmation). Minor gap: doesn't mention authentication requirements or failure modes.

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

  Conciseness3/5

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

  While helpfully structured with capitalized headers ('COMMIT', 'USE', 'IMPORTANT'), the description is overly verbose. The post-success confirmation instructions ('confirm with: The ticket URL...') could belong in system prompts rather than tool description. Some redundancy exists ('This makes it real' vs 'creates a REAL ticket').

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

  Completeness4/5

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

  Given the complexity (5 parameters, nested objects, external system interactions, no output schema), the description adequately covers critical gaps. It explains the workflow position, parameter precedence (draftId vs idea), and expected return behavior (URL, ID). Missing: explicit error handling or authentication prerequisites, though `check_auth` exists as a sibling tool.

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

  Parameters4/5

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

  With 60% schema coverage, the description adds crucial semantic information about the draftId/idea relationship: 'If a normalize_idea was just called, use the draftId... If no draftId is available, pass the full idea object.' This workflow dependency isn't fully captured in the raw schema and helps the agent choose correctly between mutually exclusive approaches.

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

  Purpose5/5

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

  The description opens with 'COMMIT an idea to GitHub, Jira, or Linear' providing a specific verb and target resource. It clearly distinguishes this from siblings like `normalize_idea` (preparatory step) and `create_idea` (internal creation) by stating this is 'the final step in the IdeaLift flow' and creates a 'REAL ticket' in external systems.

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

  Usage Guidelines5/5

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

  Excellent explicit guidance including: trigger phrases ('Commit it', 'ship it', etc.), workflow context ('final step in the IdeaLift flow: Capture → Normalize → COMMIT'), and prerequisite handling ('If a normalize_idea was just called, use the draftId'). It explicitly names the alternative parameter source and instructs 'NEVER ask the user to re-provide content that was just normalized.'

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

• check_authA
  4.6/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint: false, openWorldHint: true, destructiveHint: false. Description adds critical business logic beyond annotations: 'Normalize is FREE. Commit requires connection.' explaining the cost/auth implications. However, it doesn't explain why readOnlyHint is false despite 'check' typically implying read-only behavior, nor potential side effects.

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

  Conciseness5/5

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

  Structure is excellent: purpose statement upfront, followed by business rule, then clear conditional sections (USE/DO NOT). Despite length, every sentence serves differentiation or guidance. No repetition of structured metadata.

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

  Completeness4/5

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

  Comprehensive for a zero-parameter tool with clear workflow integration. Minor gap: lacks description of return values (no output schema exists), though the intent of 'checking status' is reasonably inferable from the name and purpose.

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

  Parameters4/5

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

  Tool accepts zero parameters (empty schema), warranting baseline score 4 per rubric. Schema coverage is trivially 100% for an empty object. No parameter clarification needed.

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

  Purpose5/5

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

  Description opens with specific verb 'Check' and resource 'connection status', clearly scoped to 'committing ideas'. It distinguishes itself from siblings like normalize_idea and create_ticket by clarifying this validates commit capability, not normalization which works without auth.

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

  Usage Guidelines5/5

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

  Contains explicit 'USE this tool when' and 'DO NOT use this tool when' sections with specific scenarios. Explicitly names sibling tools (normalize_idea, create_ticket) to clarify boundaries and provides concrete user utterance examples ('am I connected?', 'why a commit isn't working').

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

• list_destinationsA
  4.6/5.0
  Behavior4/5

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

  Annotations establish the read-only, non-destructive safety profile. The description adds critical behavioral context absent from annotations: authentication requirements ('requires IdeaLift authentication'), cost model ('Normalizing ideas is free, committing requires connection'), and workflow integration ('After normalizing an idea...'). Minor gap on error states or empty result handling.

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

  Conciseness5/5

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

  Excellent structural organization with clear visual hierarchy: purpose summary → value proposition → explicit usage conditions → authentication note. Every sentence earns its place; no redundancy or tautology. The front-loading of purpose before guidelines allows quick scanning.

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

  Completeness4/5

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

  For a parameter-less read operation with annotations covering safety, the description is highly complete. It compensates for the missing output schema by enumerating destination types (GitHub, Jira, Linear). Minor deduction for not explicitly describing the return structure format, though the enumerated examples provide sufficient inference.

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

  Parameters4/5

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

  With zero parameters in the input schema, the baseline score applies. The description correctly assumes no parameter explanation is needed, focusing instead on contextual usage guidance.

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

  Purpose5/5

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

  The description opens with a specific verb ('List') and resource ('connected COMMIT destinations'), immediately clarifying scope. It distinguishes the resource type with concrete examples (GitHub repos, Jira projects, Linear teams), making it unambiguous what this tool retrieves compared to siblings like 'list_ideas' or 'list_signals'.

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

  Usage Guidelines5/5

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

  Explicit 'USE this tool when' and 'DO NOT use this tool when' sections provide clear workflow boundaries. It specifically references sibling tool 'normalize_idea' as both a prerequisite trigger and an alternative to inline options, directly addressing when to invoke vs. when to skip. This is exemplary guidance.

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