Scores code against a repo's own incident history, rolled into an 8 index Production Reliability Index (PRI). Exposes suggest_code, save_recommendation, and get_scan_report as tools.
Scored across 8 tools
Most tools have clearly distinct purposes (scan, report, PR scoring, recommendation handling). However, get_tickets vs get_zendesk_tickets both fetch tickets, and get_dashboard_analytics vs get_support_agent_data both retrieve user-scoped page data with some metric overlap, creating mild potential for misselection.
All eight tools follow a consistent snake_case verb_noun pattern (get_*, save_*, score_*, suggest_*). No mixing of conventions or vague verbs.
Eight tools is well-scoped for a code scanning and support platform, covering the core workflow (scan, report, accept/reject, PR score, data fetch) without redundancy or bloat.
Core lifecycle is covered: suggest_code initiates a scan, save_recommendation accepts/rejects, get_scan_report retrieves the report, and score_pull_request handles PRs. Minor gaps exist (no tool to list historical scans by UUID, and tickets are read-only with no create/update/close operations).
Fetch VisionBoard dashboard analytics data for the authenticated user.
Returns the same analytics that power the VisionBoard Dashboard page:
Key metrics: total scans, dev/prod request counts, code accepts
Category breakdown (file insights)
Recent observability logs and existing best practices
Raw JSON data for further analysis
All data is automatically scoped to YOUR user account via your login token. No other user's data is ever returned.
Args: project_name: Optional project/app name to filter results. If omitted, returns aggregated data across ALL your projects. Example: "my-api", "frontend-app"
Returns: Formatted analytics summary with tables and charts-friendly data.
| Name | Required | Description | Default |
|---|---|---|---|
| project_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does disclose meaningful behavior: read-only fetching, automatic scoping to the caller's account via login token, and the guarantee that no other user's data is returned. It omits rate limits, pagination, or freshness/refresh characteristics, which keeps it from 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 content is front-loaded with the core purpose and organized into bullet lists plus Args/Returns sections, so it scans well. It is slightly longer than necessary, with mild redundancy between the bullet list and the Returns section, but nothing is seriously wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, a present output schema, and no annotations, the description supplies everything an agent needs: scope, auth behavior, filtering semantics with defaults, and the nature of the returned data. Return-value detail is already backed by the output schema, so the remaining prose is a bonus rather than a 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 description coverage is 0%, so the description must compensate, and it does: project_name is described as an optional project/app name filter, its default behavior when omitted (aggregated across ALL projects), and concrete examples ('my-api', 'frontend-app'). That fully covers the single parameter beyond what the schema offers.
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 ('Fetch VisionBoard dashboard analytics data for the authenticated user') and then enumerates the exact content: key metrics, category breakdown, observability logs, and raw JSON. This is well beyond a restatement of the name. It does not explicitly contrast itself with any sibling, so it falls just short of 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?
It states the data is 'the same analytics that power the VisionBoard Dashboard page,' which implies a context, and it explains the optional project filter's behavior. However, there is no explicit when-to-use vs. when-not guidance and no mention of the sibling tools (get_scan_report, get_tickets, etc.), leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the PDF report URL for a previous code scan.
Returns a presigned S3 URL (valid 1 hour) that opens the full scan report as a PDF. The PDF contains: project meta, PRI score, all sub-indices (FI, GC, CV, DV, DI, RS, EEI), category scores, and findings summary.
Calling this tool again with the same scan_uuid generates a fresh URL after the previous one expires.
IMPORTANT: Before calling this tool, run git remote get-url origin in the
project directory to get the GitHub URL. Normalize SSH URLs
(git@github.com:owner/repo.git) to HTTPS (https://github.com/owner/repo),
strip trailing ".git", and pass the result as repo_path. This appears on the
PDF report. If git is unavailable, pass the local directory path.
Args: scan_uuid: The scan UUID from a previous suggest_code call. repo_path: GitHub URL of the repository (e.g. "https://github.com/owner/repo").
Returns: Presigned PDF URL and scan metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| repo_path | Yes | ||
| scan_uuid | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does well: it discloses the 1-hour presigned URL lifetime, the regeneration semantics, the dependency on git availability with a documented fallback, and the exact downstream content of the PDF. It omits anything about authentication/permission requirements for the underlying scan, which keeps it from 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?
Content is front-loaded with the core action and expiration behavior before the prerequisite instructions. The only waste is mild duplication: the opening sentence about the presigned URL is restated in the 'Returns' block, and the Args/Returns sections re-cover ground already stated.
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?
An output schema exists, so the description is not obliged to explain return shapes, and it still notes that a URL plus scan metadata come back. Combined with the prerequisite and expiration disclosures, an agent has everything needed to invoke this correctly despite the absence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: scan_uuid is sourced to suggest_code, and repo_path is given both origin (a normalized GitHub URL) and a concrete format example, resolving the misleading 'path' name. Both required parameters are fully disambiguated in prose.
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 precise verb and resource ('Get the PDF report URL for a previous code scan') and enumerates exactly what the artifact contains (PRI score, sub-indices, category scores, findings). It ties the tool to its sibling suggest_code as the source of scan_uuid, so an agent can place it in the workflow without reading 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?
It states the prerequisite workflow plainly: obtain scan_uuid from a previous suggest_code call, and run `git remote get-url origin` (with SSH-to-HTTPS normalization) before invoking. It also tells the agent what to do when the URL expires, i.e. call again with the same scan_uuid. It stops short of naming any competing sibling or a 'do not use when' condition, but no real alternative exists here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch all Support Agent page data for the authenticated user.
Returns the same data shown on the VisionBoard Support Agent page:
Support Agent issues (system issues, code monitoring, telemetry signals)
Support Agent summary (signal summary + overall summary text)
TomosuScore (dev profiler) and Extended Scores (FI, DI, GC, RS, CV, DV)
Ticket statistics (active issues, fixes applied, pending fixes, acceptance rate)
Accept/Reject statistics
Server/project configuration details
Complete support_data array with per-issue fields: category, severity, component, file, issue, root_cause, suggestion, before_code, after_code, confidence, impact_details, telemetry_signal
All data is scoped to YOUR user account via your login token.
Returns: JSON object with all Support Agent sections. Claude can display, summarize, or answer questions about any part of the data.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it does a good job: it states the operation is a fetch scoped to 'YOUR user account via your login token,' and it enumerates the returned sections and per-issue fields. It does not mention pagination, data freshness, or failure behavior, but the read-only nature and auth scoping are clearly disclosed.
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-loading is good: the fetch statement comes first and the content list follows. However, the long bullet enumeration and especially the itemized per-issue fields (category, severity, component, file, root_cause, suggestion, before_code, after_code...) duplicate what the output schema already encodes, so that block does not fully earn its 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?
For a zero-parameter read tool with an output schema and no annotations, the description is nearly complete: it identifies the data source, the auth scoping, and every returned section. The only shortfall is the absence of any guidance on when to prefer this tool over similarly-scoped siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, which is the baseline-4 case; there is nothing about parameter syntax the description could add. The description does correctly reinforce that scoping is implicit from the auth token rather than a user-supplied argument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear specific verb and resource: 'Fetch all Support Agent page data for the authenticated user.' It then enumerates the exact content sections (issues, summary, TomosuScore, ticket stats, etc.), so an agent knows precisely what comes back. It never differentiates itself from siblings like get_dashboard_analytics or get_scan_report, which likely return overlapping page data.
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 via the 'same data shown on the VisionBoard Support Agent page' framing and the account-scoping note. There is no explicit when-to-use statement, no exclusion conditions, and no reference to the sibling tools an agent might confuse it with (e.g. get_tickets, get_dashboard_analytics). Minimum viable but leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch support tickets from the VisionBoard Help Portal.
Returns the same ticket data shown on the VisionBoard Help Portal page. Each ticket includes: id, ticket_id, title, priority, status, source, file_path, current_code, recommended_fix, reasoning, supportability_impact, and telemetry_signal.
All tickets are scoped to your account via your login token.
Args: ticket_number: Optional ticket ID (e.g. "001") to fetch a single ticket's full details. If omitted, returns ALL tickets.
Returns: JSON array of tickets (or a single ticket object if ticket_number is provided). Claude can display, filter, or summarize as needed.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_number | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load. It does disclose account scoping via the login token and the bulk-vs-single retrieval behavior, which is genuine behavioral context. It says nothing about pagination, result-size limits, failure modes, or whether anything is mutated (it appears read-only, but that is inferred, not stated).
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-loads the purpose, then uses clear Args/Returns sections. The field enumeration is somewhat long, and the Returns block partly duplicates the output schema, but no sentence is truly wasted and the structure is easy to scan.
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?
An output schema exists, so the return-value narrative is redundant rather than necessary; the remaining essentials — source, auth scoping, and the single-vs-all switch — are covered. The missing piece is any differentiation from the sibling ticket tool, which matters in a crowded toolset.
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 0% and the parameter has no description in the schema, so the description must compensate — and it does, giving the format ('e.g. "001"'), the optionality, and the semantic difference between supplying and omitting it. The only gap is that the accepted ID format is shown by example rather than defined.
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 — fetching support tickets from the VisionBoard Help Portal — and enumerates the returned fields, so the agent knows exactly what it gets. However, it never distinguishes this source from the sibling get_zendesk_tickets, leaving the agent to guess which ticket source applies.
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 Args section explains the one real usage decision: pass ticket_number for a single ticket, omit it for all tickets. That is useful conditional guidance, but there is no when-to-use guidance relative to alternatives like get_zendesk_tickets or the other reporting siblings, and no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch synced Zendesk support tickets for the authenticated user.
Returns Zendesk tickets that were synced when the user connected their Zendesk account via Settings → Integrations. Each ticket includes: ticket_id, subject, description, status, priority, created_at, and tags.
The user must first connect Zendesk in Settings → Integrations before tickets will be available.
Args: status_filter: Optional status to filter by (e.g. "open", "pending", "solved", "closed"). If omitted, returns all tickets. priority_filter: Optional priority to filter by (e.g. "urgent", "high", "normal", "low"). If omitted, returns all priorities.
Returns: JSON object with tickets array, total count, and filter info. Claude can display as a table, summarize trends, or answer questions.
| Name | Required | Description | Default |
|---|---|---|---|
| status_filter | No | ||
| priority_filter | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that data is *synced* (not live), that a Zendesk connection is required, and which fields each ticket contains. It omits auth scope, rate-limit, and freshness/staleness details, keeping it 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 Args and Returns sections are well front-loaded, but the closing line ('Claude can display as a table, summarize trends, or answer questions') is speculative filler that adds no invocation value, and the Returns block duplicates the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with an output schema, the description supplies the prerequisite, filter semantics, and field inventory an agent needs. Return-shape explanation is redundant with the output schema, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: both filters are explained with concrete example values ('open', 'pending', 'solved' / 'urgent', 'high', 'normal', 'low') plus explicit default semantics when omitted. It just lacks guidance on valid value casing or matching 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?
It states a specific verb and resource ('Fetch synced Zendesk support tickets for the authenticated user') and names the data source precisely. It does not, however, explicitly distinguish itself from the sibling get_tickets, leaving the agent to infer the difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a genuine prerequisite ('The user must first connect Zendesk in Settings → Integrations') and explains the default behavior when filters are omitted. It never routes the agent away from alternatives such as get_tickets or get_support_agent_data, so usage relative to siblings remains implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Accept or reject a code recommendation from a previous suggest_code scan.
Accepting a recommendation marks the corresponding category rules as passed, updating the scan's category scores in the dashboard. Rejecting only logs the decision without changing scores.
Args: scan_uuid: The scan UUID returned by suggest_code in tag. accepted: True to accept the recommendation, False to reject it. filename: Relative file path the recommendation applies to. before_code: The original code block (from the 'Before' section). after_code: The recommended replacement code (from the 'After' section). project_name: Project name (same as used in suggest_code). categories: List of category keys this recommendation belongs to (e.g. ["security", "logging"]). Used to update scores. title: Short title of the recommendation. severity: Severity level (critical / high / medium / low).
Returns: Confirmation message with the result.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| accepted | Yes | ||
| filename | Yes | ||
| severity | No | ||
| scan_uuid | Yes | ||
| after_code | Yes | ||
| categories | No | ||
| before_code | Yes | ||
| project_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose the key behavioral distinction: accepting mutates category rules and updates scan scores, while rejecting only logs. It omits other traits such as permission requirements, reversibility of an accept, and idempotency, which is why it is not 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?
Front-loads the purpose, then the accept-vs-reject behavioral delta, then the argument list – a sensible ordering that lets an agent stop reading early. The Args block is necessarily long given nine undocumented parameters, but it is formatted cleanly rather than padded.
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?
An output schema exists, so return values need not be detailed. Given a 9-parameter, 6-required mutation tool with no annotations and no schema descriptions, the description supplies the missing parameter meaning, the mode-dependent side effects, and the upstream workflow link, which is everything needed 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?
Schema description coverage is 0% – the schema gives only bare titles – so the description must compensate and it does, documenting all 9 parameters. It adds real meaning beyond names: categories keys with an example, severity's enumerated levels, the 'Before'/'After' provenance for before_code/after_code, and the tie-back of scan_uuid/project_name to suggest_code.
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 pair (accept/reject) plus the resource (code recommendation) and anchors it to a concrete upstream source: 'a previous suggest_code scan'. An agent can distinguish this from siblings like suggest_code or score_pull_request 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?
Clearly establishes the usage context (only meaningful after a suggest_code scan) and explains the two modes, with the side-effect difference between them spelled out. It does not state exclusions (e.g. what to do if scan_uuid is unknown or the recommendation is stale), so it stops short of a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a pull request for production reliability using Tomosu AI.
Analyzes PR patch diffs and returns PRI score, merge verdict, sub-index breakdown (FI/GC/CV), and top recommendations with before/after code snippets.
Before scoring the PR diff, the backend ensures a base-branch baseline (and its Tomosu Ontology Graph in Neo4j) exists and is fresh for this repo/branch, building one if missing or stale — same pipeline shape as the Tomosu GitHub App. The PR scan then runs with that graph context available (cross-file imports/symbols), same as the GitHub App gets. First scan of a repo/branch is slow (builds the baseline — can take a few minutes); repeat scans on the same branch are fast.
Call this once before writing the PR walkthrough summary. Include the returned PRI score and merge verdict at the top of the summary.
Args: repo: Repository in "owner/repo" format (e.g. "acme/backend"). pr_number: Pull request number (e.g. 42). source: Who is calling this tool. If you are Claude (Claude Code, Claude Desktop, claude.ai) you MUST pass source="claude" — this runs the full-depth scan (suggest-v3) for both the base-branch baseline and the PR, and is slower. CodeRabbit passes source="coderabbit". Any other value (or omitting it) runs the fast lightweight scan (suggest-lite). Response shape is identical.
Returns: JSON with pri, merge_ready, indices (fi/gc/cv), recommendations, total_issues (scores for the PR's changed files), plus baseline_scores {pri, fi, gc, cv} for the whole base branch (repo-level PRI) when the baseline is available.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| source | No | coderabbit | |
| pr_number | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: it discloses the implicit baseline build (and Neo4j ontology graph freshness step), that first-scan-per-branch is slow (minutes) while repeats are fast, and that the source parameter changes scan depth. These are non-obvious operational traits an agent must know before invoking.
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 purpose and return shape, then behavioral context, then args. It is somewhat long and slightly redundant between the prose return description and the Returns block, but nearly every sentence adds actionable information (latency expectations, source semantics).
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?
An output schema exists, yet the description still gives a useful human-readable summary of the response fields. Combined with the latency, baseline, and source-depth disclosures, an agent has everything needed to call this correctly and interpret results.
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 0%, so the description must compensate, and it does: it documents repo format ('owner/repo'), pr_number with an example, and critically the source parameter's semantics — which values run full-depth vs lightweight scans and that response shape is unchanged. This is meaning well beyond anything in the bare 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?
States a specific verb+resource ('Score a pull request') and names the product (Tomosu AI) plus what dimension is scored (production reliability). It is immediately distinguishable from siblings like suggest_code or get_scan_report, and the description enumerates exactly what is returned (PRI, merge verdict, FI/GC/CV sub-indices, recommendations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this once before writing the PR walkthrough summary' and to surface the PRI score/merge verdict at the top, which is clear usage context. It does not name alternative sibling tools or state when NOT to call it, so it falls short of the full when/when-not/alternatives bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze source code files and get AI-powered improvement recommendations.
This tool returns code recommendations with 'before' and 'after' code blocks. IMPORTANT: Always display the 'before' and 'after' code blocks exactly as provided in the tool output without any modification, summarization, or omission. Show every recommendation returned by this tool.
Sends files to the Tomosu suggest API (v3) which evaluates code quality across categories like security, performance, maintainability, etc.
Args:
files: List of file objects, each with 'filepath' and 'filecontent' keys.
Example: [{"filepath": "src/app.py", "filecontent": "def hello(): ..."}]
message: What to analyze or focus on (e.g., "Review for security issues").
project_name: Name of the project or repository (e.g., folder name or
GitHub repo name). Used for tracking and dashboard display.
repo_path: GitHub URL of the repository (e.g. "https://github.com/owner/repo").
IMPORTANT: Before calling this tool, run git remote get-url origin
in the project directory to get the remote URL. Normalize SSH URLs
(git@github.com:owner/repo.git) to HTTPS form
(https://github.com/owner/repo). Strip trailing ".git".
Pass the result here. If git remote is unavailable, pass the
local directory path instead.
repo_description: Short description of the repository / service purpose.
Leave empty — the backend derives this automatically.
context: Optional list of analysis categories to focus on.
Available: performance, security, maintainability, logs, error,
compliance, testing, api_observability, service_resilience,
data_integrity, observability, reliability, drift_resistance,
state_volatility, architectural_governance, support_agent_readiness, etc.
If omitted, all categories are analyzed.
scan_all: If True, backend skips the file quality-score pre-filter and scans
every file passed. Use from claude-workflow to ensure all
reliability-impacted files are scanned regardless of quality rating.
workflow_uuid: If provided, all batch calls for this workflow scan share this
UUID so the final report aggregates all batches. Generate once
with str(uuid.uuid4()) before the first batch call and pass the
same value to every subsequent batch. Also pass it as scan_uuid
to save_recommendation and get_scan_report.
Returns: Structured code recommendations with before/after code blocks, severity, line numbers, and scores. ALL code blocks must be shown to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | ||
| context | No | ||
| message | Yes | ||
| scan_all | No | ||
| repo_path | No | ||
| project_name | No | ||
| workflow_uuid | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that files are sent to an external API (Tomosu suggest API v3) and that recommendations include severity, line numbers and scores. It omits auth requirements, rate limits, whether the payload is persisted server-side, and any cost implications — meaningful gaps for a tool that transmits source code off-machine.
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?
Purpose and the before/after display mandate are front-loaded, which is good. But the display instruction is stated twice (in the opening block and again under Returns), and the long Args prose could be tightened; the response is functional but not economical.
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?
An output schema exists, so return-value structure needn't be re-explained, yet the description usefully adds the non-negotiable display contract and cross-tool UUID threading with save_recommendation/get_scan_report. One inconsistency: repo_description is documented in Args but does not appear in the input schema, which could confuse an agent assembling the payload.
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 0%, so the description must compensate — and it does, documenting all seven parameters with examples, SSH-to-HTTPS normalization rules for repo_path, the full category list for context, and the batch-aggregation semantics of workflow_uuid. This is exactly the kind of parameter explanation that lifts a 0%-coverage schema to usable.
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 — 'Analyze source code files and get AI-powered improvement recommendations' — and names the backend (Tomosu suggest API v3) and the categories it evaluates. It is clearly distinguishable from read-only siblings like get_scan_report or get_dashboard_analytics, though it never explicitly contrasts itself with score_pull_request, the closest sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides strong operational guidance embedded in the parameter docs (run `git remote get-url origin` before calling, generate one workflow_uuid per batch and reuse it, use scan_all from claude-workflow), which routes multi-call usage effectively. However, it gives no explicit when-to-use guidance relative to siblings such as score_pull_request or save_recommendation; the reader must infer the workflow from scattered parameter notes.
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_dashboard_analyticsget_scan_reportget_support_agent_dataget_ticketsget_zendesk_ticketssave_recommendationscore_pull_requestsuggest_code
Add one secure layer between your agents and this server.