Server Quality Checklist

Tool Scores

• kira_share_scarA
  4.1/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces that nothing is uploaded and explains the process (re-sanitizes, generalizes, returns a URL). 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.

  Conciseness4/5

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

  Two sentences, front-loaded with the main action. The second sentence is dense but efficient. No wasted words.

  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 full schema coverage, annotations, and no output schema, the description explains input constraints, output format, and a key constraint (no upload). It references related tools and mentions rewards, making it complete enough for an AI agent.

  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%, so parameters are documented. The description slightly adds context (scar_id from specific tools), but does not significantly enhance the schema descriptions. Baseline 3 is appropriate.

  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 uses a specific verb ('Promote') and resource ('personal scars into community submission'), clearly distinguishes from siblings by specifying input from kira_personal_brief/kirk_lookup and the output format (GitHub issue URL).

  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?

  It states when to use (after getting a personal scar id) and what not to do ('NOTHING is uploaded, show the result and let them submit'). It doesn't explicitly compare to siblings, 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.

• kira_getA
  4.2/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, indicating a safe read. The description adds that retrieval is for full instructions, and notes the token-saving pattern with lookup. However, it does not detail response size or potential rate limits, but these are less critical given 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.

  Conciseness5/5

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

  Two sentences, each serving a distinct purpose: first defines the tool's function, second provides usage guidance. No wasted words.

  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?

  The description covers purpose and usage pattern well. For a simple tool with one parameter and no output schema, it is largely complete. A minor gap is not specifying the structure of 'full instructions', but it is adequate given the domain context.

  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 a parameter description that explains ID format via examples. The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

  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 verb 'Get' and the resource 'full instructions for a specific skill or scar by ID'. It distinguishes from sibling tool kira_lookup by noting that this tool retrieves details while lookup only returns summaries.

  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?

  Explicitly instructs to call this tool AFTER kira_lookup to get step-by-step instructions. Explains that kira_lookup returns summaries to save tokens, so this tool provides the full details.

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

• kira_premortemA
  4.3/5.0
  Behavior4/5

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

  Annotations confirm readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description aligns fully, adding details about return structure (scars, hit_count, heat score, minutes saved). No contradiction; description enriches the safety profile.

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

  Conciseness4/5

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

  The description is a single, dense paragraph that front-loads purpose and then details return values. It earns its sentences, though it could benefit from bullet points for readability. Not overly long.

  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?

  No output schema exists, so the description must detail return values, which it does: 'each hotspot includes the mistake, the fix ('instead'), a relative heat score, and estimated minutes saved... plus an aggregate prevention value.' It also covers edge cases like 'near_scars'. Adequate for the tool's complexity.

  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. The description restates the obvious for goal and context but does not add new semantic constraints or examples beyond the schema fields. Minimal added value.

  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 and resource: 'Run a PRE-MORTEM' and 'return a heat map of the past failure patterns.' It clearly distinguishes itself from siblings by emphasizing its proactive role before task execution, unlike tools like kira_lookup or kira_route.

  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?

  Explicitly states 'Call this FIRST for any non-trivial task' and provides a clear after-action: 'then read each hotspot's 'instead' and use kira_lookup / kira_route to plan the actual work.' It also describes behavior for low-match scenarios ('near_scars').

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

• kira_record_failureA
  4.4/5.0
  Behavior5/5

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

  Discloses key behaviors: local storage path, sanitization of personal data ('keys, paths, emails redacted'), and side effect of influencing future runs. Annotations are non-contradictory; description adds significant 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.

  Conciseness3/5

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

  Description is clear and front-loaded but longer than necessary; includes some explanatory phrases that could be trimmed (e.g., 'so future runs on this machine can avoid the same wall'). Still well-structured.

  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 tool with 7 parameters and no output schema, the description covers purpose, usage timing, privacy, and storage location. Lacks mention of return value or idempotency, but overall comprehensive.

  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?

  Schema coverage is 100%, so baseline is 3. Description adds meaningful context, explaining how each parameter is used (e.g., 'title becomes the scar title', 'mistake is what the agent did wrong', 'instead is the fix'), plus sanitization detail.

  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 clearly states verb 'capture' and resource 'personal scar', explicitly distinguishing itself as local-only failure notes stored under ~/.kira/personal-scars/, differentiating from siblings like kira_share_scar.

  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?

  Explicitly states when to call: 'immediately after a task needed extra attempts or threw an error.' Notes privacy constraints ('never uploaded'), implying when not to use (if sharing is needed), but does not name specific alternative tools.

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

• kira_statusA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate read-only and idempotent. Adds specific details on what is reported (version, tier, telemetry, counts, log path) and implies low cost.

  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, highly concise with no wasted words. Front-loaded with main function and efficient.

  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?

  Covers key outputs without needing output schema, but lacks hint about return format. Minor gap for completeness.

  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?

  No parameters, so description does not need to add param info. Baseline score of 4 is appropriate; implicit that no input is required.

  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?

  Clearly states it reports installed state including version, tier, telemetry, counts, and log location. Distinguishes from sibling 'lookup' by noting efficiency.

  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?

  Explicitly calls it out as the tool to use for install state, and contrasts with 'lookup' to avoid exhaustive searches. Could further differentiate from other siblings.

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

• kira_reportA
  4.6/5.0
  Behavior5/5

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

  Description adds significant behavioral context beyond annotations: mentions scar system, telemetry sent only on full consent, and details for retry/failure. No contradiction with annotations (readOnlyHint false, openWorldHint true supports this write 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?

  Two sentences: first states purpose, second details usage and statuses. No fluff, every word adds value. Perfectly front-loaded.

  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?

  Sufficient for a reporting tool with 4 parameters and no output schema. Covers when-to-call, statuses, note requirements, and telemetry consent. Could add return value hint, but not critical.

  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?

  Description elaborates on status and note parameters beyond schema definitions (links statuses to scar system, note required for retry/failure). Schema covers 75%, description fills gaps for status (enum meaning) and note (scar system purpose).

  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 tool reports the outcome of applying a Kira skill, with a specific verb and resource. It also differentiates from sibling tools like kira_get or kira_route by emphasizing the reporting function and the ALWAYS call context.

  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?

  The description explicitly says to call this after completing or failing a Kira task, lists statuses, and instructs on note inclusion for retry/failure. It implies mandatory use, but does not explicitly state when not to use or compare to alternatives.

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

• kira_consentA
  4.7/5.0
  Behavior5/5

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

  Description discloses behavior for each level, including that 'off' still writes a local log and 'full' uploads sanitized notes. Annotations (idempotentHint=true) are consistent; no contradiction adds extra context about persistence and redaction.

  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?

  Five sentences efficiently cover purpose, levels, query behavior, and reference to external doc. Front-loaded and no wasted words.

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

  Completeness5/5

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

  For a simple set/query tool with one parameter and no output schema, the description covers all key behaviors (query, set, levels) and points to PRIVACY.md for wire format, making it complete.

  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?

  Schema has 100% coverage with enum and description for the single parameter 'level'. Description adds meaning by detailing the data sent at each level, going beyond the schema's brief description.

  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 clearly states the tool sets telemetry consent level for kira_report with three distinct levels explained. It uniquely addresses consent among sibling tools (kira_get, kira_lookup, etc.).

  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?

  States when to query (no arguments) and refers to PRIVACY.md for details. Does not explicitly exclude usage scenarios or list alternatives, 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.

• kira_routeA
  4.7/5.0
  Behavior4/5

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

  Annotations already provide readOnly, idempotent, non-destructive hints. Description adds context about return structure (ordered steps with Skill and Scars) and usage workflow, but no additional safety or auth details.

  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?

  Three sentences front-loaded with main action, then usage guidance. No redundant information.

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

  Completeness5/5

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

  Given read-only, idempotent nature, no output schema, and full parameter descriptions, the description sufficiently covers what the tool does, when to use, and how to integrate with other tools.

  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?

  Schema coverage is 100%, baseline 3. Description adds value by explaining the 'goal' parameter with concrete examples and reinforcing the role of 'context'.

  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?

  Clearly states it plans a complete route for a goal, with examples distinguishing it from looking up individual skills. Explicitly contrasts with sibling tools like kira_lookup.

  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?

  Explicitly says to use this FIRST for broad goals, then execute steps sequentially calling kira_report after each. Provides when-not-to-use (instead of individual skills lookup).

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

• kira_lookupA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds substantial behavioral context: it explains the ordering logic of results (skills sorted by community/vendor, scars sorted by criticality and origin), and warns that both skills and scars are returned. It also mentions that personal failures recorded via kira_record_failure are included. No contradiction with annotations; description enriches understanding.

  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 is well-structured with a clear opening sentence defining the tool's purpose, followed by ordering details, and then numbered steps for the agent. Every sentence adds value without unnecessary verbosity. It is appropriately sized and front-loaded.

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

  Completeness5/5

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

  Given the tool's complexity (returns two types of data with specific ordering and agent usage steps) and no output schema, the description is remarkably complete. It explains exactly what the return values contain and how the agent should act on them, leaving no ambiguity.

  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?

  Schema coverage is 100% with descriptions for both keyword and context. The description adds that the keyword is case-insensitive and refers to it as a 'firing keyword or phrase', and mentions context for disambiguation. While the schema already conveys core meaning, the description provides slightly more context about how parameters affect the lookup, justifying above-baseline score.

  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 it looks up skills (how to do it) and scars (what to avoid) for a given keyword. It distinguishes from sibling tools like kira_record_failure and kira_share_scar by specifying it returns both types with detailed ordering (skills: community first then vendor; scars: critical first, own recorded before shared, then by frequency). This is a specific verb+resource with clear outcome.

  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?

  The description provides explicit step-by-step instructions for the agent: read all scars first to avoid repeating past failures, then read skills, announce the chosen skill's declaration field, and follow instructions while watching for scar patterns. It also notes that personal scars from kira_record_failure on this machine fire here, adding context. This gives clear when and how to use the tool, including exclusions (avoid repeating failures).

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

• kira_personal_briefA
  5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: 'Personal scars are LOCAL-ONLY — this reads them from disk and never touches the network.' It also describes return format (top-N by recency, most recent first, with mistake and alternative).

  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?

  Three dense, information-rich sentences with no wasted words. Front-loaded with the core purpose.

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

  Completeness5/5

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

  Given two simple optional parameters and no output schema, the description fully explains what the tool returns and under what conditions. No gaps.

  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?

  Schema description coverage is 100%, but the description adds extra context: 'Pass 'limit' to change how many, and 'contexts' to keep only scars relevant to the current project.' It clarifies that untagged scars are always kept, which is not in 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 tool's purpose: 'Surface your most recent PERSONAL scars.' It specifies the resource (personal failure notes), the action (surface), and the source (local-only disk). It distinguishes from siblings by emphasizing local-only nature and connection to kira_record_failure.

  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?

  Explicitly advises when to use: 'Call this at the START of a session (ideally from a SessionStart hook).' This is strong, actionable guidance. It also implicitly differentiates by noting it reads local data never touching network, contrasting with other tools that might access remote data.

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