Read-only sample shop with captured bug evidence. No account or key needed.
Scored across 14 tools
Each tool targets a clearly distinct resource or scope: bug detail, events, history, occurrences, users, live occurrences, groups, recommendations, stats, and repro context. Overlapping-looking list tools are explicitly differentiated with guidance like 'prefer list_bug_groups for triage' and 'use this instead of list_bugs for what to work on.'
All tool names use snake_case with a predictable verb_noun pattern (get_bug_*, list_bug_*, list_projects, get_project_stats, etc.). Minor variants like list_recommended_critical remain readable and consistent with the overall convention.
With 14 tools, the set is well-scoped for bug investigation and triage. Each tool has a distinct role and none appear redundant or trivial.
The read/investigation surface is rich, covering bugs, users, occurrences, events, history, similar bugs, groups, and stats. However, there are notable missing mutation/lifecycle operations: no create, update, assign, merge, or delete tools, and descriptions reference bulk_update_bugs, which is not present in the tool list.
Get full details of a bug including title, description, severity, status, reporters, AI summary, environment info, report count, affected_user_count, repeat_user_count, and user_spread (user_specific vs widespread). Use get_bug_users for the per-user roster.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | The bug ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive, so safety is covered. The description adds genuinely new behavior context: it is a full-detail fetch (no projection/filtering) returning AI summary, environment, and the three counts plus user_spread classification — information the agent cannot get from annotations and would not guess.
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?
Front-loaded with the verb and resource, then the field enumeration, then the sibling routing sentence. The field list is long but earns its place because there is no output schema; only minor tightening is possible.
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, enumerating returned fields is exactly the right compensation, and the user_spread semantics (user_specific vs widespread) are spelled out. Minor gap: no mention of behavior for an unknown/deleted bugId or whether closed bugs are returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single bugId parameter (uuid, required), so the schema carries the full burden already. The description adds nothing about the identifier's format or source, which is acceptable but leaves it at the baseline for high-coverage schemas.
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?
Specific verb+resource ('Get full details of a bug') plus an enumerated field list that tells the agent exactly what data comes back. It explicitly distinguishes itself from the sibling get_bug_users, so the agent can separate the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes per-user data to get_bug_users, which is a real alternative and a real condition. It does not cover the other direction — e.g. when to use this versus list_bugs or get_bug_history — but the single-entity read case is clear from 'full details of a bug'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get session events for a bug (DOM, network, console, clicks, errors). Prefer passing occurrenceId so events are not mixed across captures.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by event type (e.g., "click", "console-error", "network") | |
| bugId | Yes | The bug ID | |
| limit | No | Max events to return | |
| offset | No | Continue from the previous response nextOffset | |
| occurrenceId | No | Pin events to one occurrence (recommended) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that omitting occurrenceId can mix events across captures — but says nothing about volume, ordering, or pagination behavior beyond what the schema documents.
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 filler, with the core purpose front-loaded and the key parameter caveat immediately after. Every clause carries information the agent can act on.
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 paginated list tool with full schema coverage and clear annotations, the description covers purpose, scope, and the main invocation pitfall. A brief note on result volume or how offset relates to nextOffset would close the last gap.
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 earns a bump by explaining the consequence of occurrenceId ('events are not mixed across captures'), which adds rationale beyond the schema's terse '(recommended)' label. The other parameters (type, limit, offset) get no added semantic detail in the 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?
States a specific verb and resource ('Get session events for a bug') and enumerates the event categories returned (DOM, network, console, clicks, errors), so the agent knows exactly what this returns. It does not explicitly contrast itself with the sibling get_bug_occurrences or get_bug_history, which would be needed for a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives actionable invocation guidance ('Prefer passing occurrenceId so events are not mixed across captures'), which tells the agent when to use a specific parameter path. It stops short of explicit when-not-to-use guidance or naming the sibling to use when you want the list of occurrences rather than raw events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full audit trail of status/severity changes and assignments on a bug, including who changed what and when.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | The bug ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful content-level context about what the trail contains, but says nothing about ordering, completeness, or whether the history is truncated.
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?
A single front-loaded sentence with zero filler; the resource scope and the returned dimensions are packed into one clause 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?
With no output schema, the description does the work of conveying the return shape (recorder, changed field, timestamp). Pagination and ordering behavior remain unstated, which is a small gap for an audit-trail tool that could return many entries.
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 single required 'bugId' uuid parameter, so the schema fully documents the input. The description adds no additional semantics about the ID (format, scoping, or validity), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a well-scoped resource: the audit trail of status/severity changes and assignments on a bug, plus the 'who/what/when' dimensions. It is meaningfully distinguishable from get_bug and get_bug_events by the emphasis on change history, though it never names those siblings explicitly.
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 when to use it (you want change history rather than current state), but it never states 'use this instead of get_bug_events' or any exclusion or precondition. The agent must infer the choice from the resource phrasing alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the individual occurrences grouped under a bug. Use this to see which users, sessions, releases, or environments were affected.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | The grouped bug ID | |
| limit | No | Max occurrences to return | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closedWorld), so the bar is lower. The description adds that the result is the per-occurrence level rather than the aggregate, which is useful context. It says nothing about ordering, sampling, or how the paginated result is capped or ordered, which matters because there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler, and the core 'what it lists' statement comes first, followed by the usage hint. Nothing is redundant or misplaced.
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 safety profile, parameters, and result semantics are all covered between the annotations, the schema, and the description. The one real gap is that a paginated list with no output schema would benefit from a line on ordering or how to page through results, which the description does not provide.
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 bugId, limit (default 50, max 200), and offset are already fully documented. The description adds no extra meaning, syntax, or hints about which parameter to tune. With the schema doing all the work, the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: 'List the individual occurrences grouped under a bug'. That is clearly distinct from the grouped view a sibling like get_bug would show. It never names a sibling explicitly, though, so an agent must infer the split between this, get_bug_users, and get_live_occurrences.
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?
'Use this to see which users, sessions, releases, or environments were affected' gives concrete conditions for calling the tool. It does not name alternatives or say when not to use it, so the agent has to work out the overlap with get_bug_users and get_live_occurrences on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who hit this bug: one row per affected end user (the app's identify() userId, else reporter email, else an anonymous IP-hash key) with firstSeen, lastSeen, occurrenceCount, platforms (web/ios/…), lastRelease and lastOccurrenceId. Pass a row's userKey to get_user_timeline to see everything that user experienced across bugs, or to get_repro_context via occurrenceId=lastOccurrenceId.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | The grouped bug ID | |
| limit | No | Max users to return (newest last-seen first) | |
| offset | No | Pagination offset |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral context: the fallback identity scheme (userId → reporter email → IP hash) which determines what a userKey actually represents, plus the per-user field set that comes back.
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 identity rule and follow-up routing; no filler. The field enumeration is dense but each item is informative, though it does make the first sentence long.
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?
There is no output schema, so the description must describe the return shape — and it does, naming firstSeen, lastSeen, occurrenceCount, platforms, lastRelease and lastOccurrenceId. Combined with the chaining guidance, an agent has everything needed to call 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 description coverage is 100% and all three parameters (bugId, limit, offset) are documented there, including ordering and bounds, so the schema carries the load. The description adds no syntax or format detail for them, which is the correct baseline-3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (affected end users of a bug) and the exact identity-resolution chain used to key them (identify() userId, else reporter email, else anonymous IP-hash). This is distinguishable at a glance from siblings like get_bug_occurrences or get_bug_events, which deal with events rather than people.
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 what to do with the results — pass userKey to get_user_timeline, or occurrenceId=lastOccurrenceId to get_repro_context — which is strong downstream routing. It does not state when to prefer this over the occurrence-level siblings, so the selection boundary is left partly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the credential workspace. Agent PATs resolve only their own workspace; human sessions use BUGTAPE_ORG_ID.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a safe, idempotent read. The description adds genuinely non-obvious resolution semantics: agent PATs are scoped to their own workspace, while human sessions fall back to the BUGTAPE_ORG_ID env var. That resolves an ambiguity an agent would otherwise have to discover empirically.
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 filler, and the core purpose leads before the resolution caveats. Every clause carries distinct information — the second sentence is pure added value, not restatement.
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 there is no contract for the return shape, so the agent doesn't know which fields (id, name, slug) come back. For a zero-parameter lookup this is a minor gap, and the auth-resolution context is otherwise sufficient to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The description correctly avoids inventing parameter guidance and instead spends its words on resolution behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return the credential workspace'), so an agent knows it's a lookup of the caller's current org context. It is clearly distinct from every sibling, which all deal with bugs, projects, or stats. The only friction is the name/title/description drift between 'org' and 'workspace', which the reader must reconcile.
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 the tool answers 'which workspace am I operating in?', but never states when to call it or what to do with the result. Usage is inferred rather than stated, and no alternative is named — which is acceptable only because no sibling plausibly competes for this purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most recent occurrences across the organization. Useful for live monitoring and tester workflows. Honors deliveryFeed (tool arg, else PAT / project).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max live occurrences to return | |
| deliveryFeed | No | Delivery feed: all, urgent_critical, or ui_ux. Defaults to the PAT or project setting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds functional behavioral context by stating that 'deliveryFeed' honors existing system settings (PAT/project) as a fallback if the argument is not specified. This adds operational behavior beyond what is present in the schema or 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 two sentences are highly efficient. The first establishes the scope, and the second front-loads critical operational logic regarding the arguments.
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 definition is complete. It clearly defines the scope (organizational, recent), the primary use case, and the specific operational fallback logic for key inputs, which is sufficient for a read-only monitoring 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?
With 100% schema description coverage, the description provides little specific meaning regarding the parameters. It merely reinforces the `deliveryFeed` argument's behavior as a default.
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 immediately defines the tool's purpose: to retrieve the most recent occurrences across the organization. It explicitly identifies its use case for live monitoring and testing workflows.
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?
While it states when the tool is 'useful' (for live monitoring), it does not provide explicit guidance on when it should or should not be used in relation to other available bug or event tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate statistics for a project (server-computed over bugs in the elected delivery feed, not a sample): counts by status and severity, daily timeline, top unresolved bugs by report count, MTTR, health score, and previous-period comparison.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Timeline window in days (default 30) | |
| projectId | Yes | Project ID | |
| deliveryFeed | No | Delivery feed: all, urgent_critical, or ui_ux. Defaults to the PAT or project setting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real behavioral context beyond them: results are server-computed over the elected delivery feed (not a sampled approximation), and the deliveryFeed parameter defaults to PAT or project settings. It stops short of disclosing cost, latency, or pagination, but that is minor.
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?
A single sentence front-loads the verb and resource before the metric list, and every clause carries information (the 'not a sample' caveat is the strongest value-add). It is dense but not padded; a slight readability cost from the long comma-separated metric enumeration keeps it off a 5.
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 responsibly enumerates the returned metrics so the agent knows what it receives, and all parameters are schema-documented. What remains unstated is the response's relationship to the days window (e.g. whether MTTR and health score are scoped to that window) and whether cost scales with it — a modest gap for an analytics 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 all three parameters (days, projectId, deliveryFeed) are already documented with defaults, bounds, and enum values. The description reinforces that the feed election affects which bugs are aggregated but adds no syntax or windowing detail beyond the schema, so 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?
States a specific verb and resource ('Get aggregate statistics for a project') and enumerates exactly what is aggregated: status/severity counts, timeline, top unresolved bugs, MTTR, health score, period comparison. This is clearly distinguishable from siblings like get_bug or list_bugs, which return individual records rather than aggregates.
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?
Usage is implied rather than stated: 'aggregate statistics for a project' signals this is the aggregation counterpart to list_bugs/get_bug, and 'server-computed... not a sample' hints it should be preferred over client-side counting. But there is no explicit when-to-use/when-not or named alternative, leaving the routing inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build an agent-consumable reproduction pack: evidence (timeline, status, env) separate from inference (AI summary). Prefer occurrenceId so sessions are not interleaved. Not raw rrweb. Same pack as resources/read bugtape://bugs/{bugId}/repro.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | The bug ID | |
| eventLimit | No | Max raw events to scan before summarizing | |
| occurrenceId | No | Pin to one occurrence. If omitted, uses the latest occurrence when available. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the standard read-only annotations, the description discloses key behavioral traits of the function: it actively *build* a pack rather than just returning raw data, and it provides the specific resource path format ('resources/read bugtape://bugs/{bugId}/repro'), which is crucial for understanding the tool's internal workflow.
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 highly dense and professional, front-loading the core concept of building an agent-ready package. The language is precise, with every clause serving to clarify the scope or method of operation.
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 complexity implied by building a 'reproduction pack,' the description covers the function's intent, input constraints, and structural behavior (evidence vs. inference). It provides sufficient context for an agent to call the tool correctly without needing an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds vital semantic meaning to the parameters, particularly regarding 'occurrenceId,' explaining that it is used to 'Pin to one occurrence' and prevent interleaving. This functional guidance goes significantly beyond merely listing parameter names.
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 terminology ('agent-consumable reproduction pack') and clearly differentiates the output structure into 'evidence' and 'AI summary' (inference). This distinct definition sets it apart from simple retrieval tools like get_bug_events or get_bug_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on preference and constraint: 'Prefer occurrenceId so sessions are not interleaved' and clarifies what it is NOT ('Not raw rrweb'). This proactively guides the agent on the best way to use the tool compared to simpler retrieval methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find other bugs similar to the given bug, ranked by similarity score (0-100, fingerprint + title overlap). Returns up to 5 matches. Useful before merging or triaging.
| Name | Required | Description | Default |
|---|---|---|---|
| bugId | Yes | The bug ID to find similar bugs for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond that: similarity is computed from fingerprint and title overlap, scores are 0-100, and at most 5 matches are returned.
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 filler. The core action, ranking method, result limit, and use case are 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 single-parameter read tool with rich annotations, the description covers ranking, score range, and result count. It does not describe the shape of each returned match, which is a minor gap because no output schema 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 coverage is 100%, and the single bugId parameter is fully documented in the schema. The description only restates that it accepts a 'given bug' and adds no syntax or format details beyond the UUID schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: find other bugs similar to a given bug. It adds ranking criteria, score range, and a result cap, which distinguishes it from sibling tools like get_bug or list_bug_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when the tool is useful: before merging or triaging. It does not name explicit alternatives or when-not conditions, so it falls short of a perfect usage-guidance score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grouped triage view: bugs collapsed across pages by error signature (one group per distinct error within a project, even when dedup created many bug rows). Each group includes projectId + groupKey (the stable group identity), a representative sampleBugId/sampleTitle, instanceCount, occurrenceCount, sessionCount, userCount, maxSeverity, topStatus, signalReason (why the classifier flagged it), browsers/oses, platforms (web/ios/android/react-native/flutter/server — one issue can span several), and anyRegression. Pass both projectId and groupKey as one groupRefs entry to bulk_update_bugs. Legacy groupKeys are accepted only when unique across the organization and are rejected when ambiguous. Prefer this over list_bugs for triage.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort key: last_seen (default), first_seen, count (occurrences), severity, title, signal (regressions first), assignee (display name, unassigned last) | last_seen |
| limit | No | Number of groups (default 20) | |
| offset | No | Pagination offset | |
| search | No | Search text in title and description | |
| status | No | Filter by per-bug status (groups also expose aggregated topStatus) | |
| assignee | No | 'unassigned', or a user id from list_team — narrows to bugs assigned to that person (or none) | |
| platform | No | Only groups with an occurrence captured on this platform | |
| severity | No | Filter by per-bug severity | |
| direction | No | Sort direction for the chosen key (default desc; ties break on last_seen desc) | desc |
| projectId | No | Filter by project ID | |
| unresolved | No | true = only groups whose aggregated topStatus is not resolved/silenced | |
| deliveryFeed | No | Delivery feed: all, urgent_critical, or ui_ux. Defaults to the PAT or project setting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real value beyond that: it explains grouping semantics, enumerates the returned group fields, and discloses the legacy groupKey acceptance/ambiguity rule. Pagination behavior is left to the schema, keeping it just short of a 5.
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 grouping definition and the list_bugs routing are front-loaded, and the field list is informative rather than filler. The single dense paragraph is slightly packed but every sentence carries operational meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter, zero-required read tool with no output schema, the description covers grouping logic, returned fields, and the legacy-key edge case. It is complete enough to call correctly; only minor items like pagination/ordering behavior are left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 12 parameters including enums and defaults; baseline 3 applies. The description adds cross-tool meaning for projectId/groupKey (groupRefs format, legacy key caveats) but does not enrich sort/limit/status semantics 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?
States a specific verb and resource (grouped triage view of bugs collapsed by error signature) and explicitly contrasts it with list_bugs. An agent can distinguish this from list_bugs and the get_bug* siblings without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the alternative explicitly ('Prefer this over list_bugs for triage') and gives the condition that selects it. It also explains the cross-tool handoff (pass projectId + groupKey as one groupRefs entry to bulk_update_bugs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List bugs for the organization (flat, one row per deduplicated report). Supports filtering by status, severity, project, platform, deliveryFeed (all | urgent_critical | ui_ux), and text search. Each row includes affected_user_count, repeat_user_count, and user_spread (user_specific vs widespread). Diagnostic-class signals are excluded by default. Prefer list_bug_groups for grouped triage.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results (default 20) | |
| offset | No | Pagination offset | |
| search | No | Search text in title and description | |
| status | No | Filter by bug status | |
| platform | No | Only bugs with an occurrence captured on this platform | |
| severity | No | Filter by severity | |
| projectId | No | Filter by project ID | |
| deliveryFeed | No | Delivery feed: all, urgent_critical (severity Score ≥ high and confidence ≥ 0.80), or ui_ux (is_ui_ux Noul ≥ 0.70). Defaults to the PAT or project setting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes significantly beyond the structural hints provided in the annotations by specifying a constraint on the data itself: 'Diagnostic-class signals are excluded by default.' This is a critical piece of operational behavior that a user must know before trusting the results.
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 highly efficient. It front-loads the scope, immediately lists the capabilities (filtering/search), details the output schema, and provides sibling routing instructions in a compact, linear flow. There is zero wasted space.
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 complexity of the 8 input filters and the lack of an output schema, the description is fully complete. It defines the data format, the filtering logic, and the specific metadata available in the results, leaving the agent with no gaps in understanding its functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema coverage is 100%, the description adds high-value semantic information regarding the *output* structure, detailing that 'Each row includes affected_user_count, repeat_user_count, and user_spread.' This context is vital for the agent to correctly interpret the tool's results.
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 purpose—to 'list bugs for the organization'—and immediately differentiates the output format ('flat, one row per deduplicated report'). Crucially, it provides strong routing guidance by stating, 'Prefer list_bug_groups for grouped triage,' which directly addresses the relationship to a sibling 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?
This tool provides excellent usage guidelines by defining when it should *not* be used for certain tasks. The explicit instruction to 'Prefer list_bug_groups for grouped triage' gives the agent a clear decision tree for when to use this specific listing tool versus others in the ecosystem.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects in the organization with their bug counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety behavior is covered. The description adds the useful detail that results include bug counts and are org-scoped, but says nothing about result size, ordering, or truncation for organizations with many projects.
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?
A single front-loaded sentence with no filler; scope and return content are stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only listing tool with full annotation coverage and no output schema, the description conveys enough to call it correctly and hints at the payload (bug counts). Only scale/ordering expectations are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is no parameter semantics to explain; the description correctly does not invent any. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (projects) plus an explicit scope (organization) and a notable return attribute (bug counts). It is distinguishable from siblings like get_project_stats and get_current_org, though it does not name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the discovery/enumeration tool for projects, but the description never states when to prefer it over get_project_stats or get_current_org, nor any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start here. Returns sentToYou first: bugs a person sent you with "Send to agent" (fix these first), then the prefiltered agent inbox: one row per signature group, new unique issues scored critical/high (or regressions). id is the best qualifying member. member_id_sample is at most 8 member ids; instance_count is the full count and instances_path lists the rest. Use this instead of list_bugs for what to work on. Diagnostic, silenced, and agent-acked rows are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | ISO timestamp; only rows recommended after this | |
| projectId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds ordering semantics, signature-group deduplication, the fact that `member_id_sample` is truncated at 8 while `instance_count` is the true total, and that `instances_path` holds the remainder. These are non-obvious behavioral traits an agent could not infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with 'Start here.' and the highest-priority result class before the fallback inbox. Dense with backticked field names in a single paragraph; every clause carries information but the packing slightly hurts scanability.
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 carries the return-shape burden and does so well (row = signature group, `id` is best member, sample vs. full counts). Missing only parameter guidance for `limit`/`projectId`, a minor gap for an otherwise self-contained definition.
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 only 33%: `since` is documented, but `limit` and `projectId` are described nowhere. The description spends its words on return-value semantics rather than parameter meaning, so the coverage gap is not compensated — though both undocumented params are conventional and appear across sibling list tools.
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?
Concrete verb + resource with explicit scope: returns person-sent bugs first, then a deduplicated critical/high (or regression) inbox. It directly names the sibling it replaces ('Use this instead of list_bugs'), so an agent can discriminate it without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Start here' plus 'Use this instead of list_bugs for what to work on' gives an explicit when-to-use and names the alternative. It also states exclusion conditions (diagnostic, silenced, agent-acked rows) so the agent knows what will not appear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_bugget_bug_eventsget_bug_historyget_bug_occurrencesget_bug_usersget_current_orgget_live_occurrencesget_project_statsget_repro_contextget_similar_bugslist_bug_groupslist_bugslist_projectslist_recommended_criticalCustom metal-print storefront: catalog search, product details, shipping, reviews. Read-only.
Read-only product discovery, merchant trust, shipping and returns for SVV-Schatzoekers.
Shop the Is Agentic store with read-only catalog discovery, gift recommendations and cart links.
Free open check: can an AI agent reach checkout on this store? Advisory; ARC stops before payment.
Add one secure layer between your agents and this server.
