Dieses Repository enthält einen kleinen MCP-Server zum Abfragen der Apache Incubator-Gesundheitsberichte aus tools/health/reports.
Er analysiert das von den Apache-Gesundheitstools verwendete Markdown-Berichtsformat und stellt MCP-Tools bereit für:
das Auflisten verfügbarer Podling-Berichte
das Suchen nach Podling-Namen
das Abrufen einer analysierten Zusammenfassung für einen Podling
das Zurückgeben des rohen Markdown-Berichts
das Zurückgeben von Metriken für ein spezifisches Zeitfenster
das Vergleichen eines Podlings über zwei oder drei Zeitfenster hinweg
das Auflisten unterstützter Metriken und Zeitfenster
das Ranking von Podlings nach einer Metrik innerhalb eines Zeitfensters wie 3m, 6m oder 12m
Verweisen Sie den Server auf ein lokales Verzeichnis, das Markdown-Dateien enthält wie:
reports/
Amoro.md
Iggy.md
...Der Parser ist auf die aktuelle Apache-Berichtsstruktur ausgelegt, insbesondere auf den Abschnitt ## Window Details.
Related MCP server: IPMC MCP
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install .Für die lokale Entwicklung:
make install-devhealth-mcp --reports-dir /path/to/incubator/tools/health/reportsDer Server verwendet stdio und ist daher dafür vorgesehen, von einem MCP-Client gestartet zu werden.
Für die lokale Entwicklung ohne vorherige Installation können Sie den stdio-Server weiterhin direkt starten:
python3 server.pyDas Paket behält außerdem apache-health-mcp als abwärtskompatiblen Befehls-Alias bei.
Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json und fügen Sie Folgendes hinzu:
{
"mcpServers": {
"apache-health": {
"command": "health-mcp",
"args": [
"--reports-dir",
"/path/to/incubator/tools/health/reports"
]
}
}
}Starten Sie anschließend Claude Desktop neu. Wenn Sie die Installation in einer virtuellen Umgebung vorgenommen haben, die sich nicht in Ihrem PATH befindet, verwenden Sie den absoluten Pfad zum health-mcp-Befehl dieser Umgebung.
health_overview
Gibt das Berichtsverzeichnis, die Anzahl der Berichte, die Podling-Liste und das Datum der letzten Generierung zurück.
list_podlings
Gibt die im Berichtsverzeichnis verfügbaren Podling-Namen zurück.
search_podlings
Durchsucht Podling-Namen nach einer nicht-case-sensitiven Teilzeichenfolge mit einem optionalen Ergebnislimit.
get_report_summary
Gibt analysierte Fenster-Metriken für einen einzelnen Podling zurück.
get_report_markdown
Gibt das rohe Markdown für einen einzelnen Podling-Bericht zurück.
get_window_metrics
Gibt Metriken für einen Podling und ein Zeitfenster wie 3m, 6m, 12m oder to-date zurück, einschließlich normalisierter Trendwörter wie up, down und flat unter trends.
compare_windows
Gibt Metriken für einen Podling im direkten Vergleich über zwei oder drei Zeitfenster hinweg zurück, einschließlich normalisierter Trendwörter unter den trends jedes Fensters.
query_metric_rankings
Erstellt ein Ranking von Podlings nach einer analysierten Metrik wie commits, prs_merged, dev_messages, bus50 oder median_merge_days.
list_metrics
Gibt die unterstützten Metriknamen und verfügbaren Zeitfenster für Abfragen zurück.
Diese Beispiele zeigen die Arten von Fragen, die ein Benutzer an einen mit diesem Server verbundenen MCP-Client stellen kann.
"Welche Apache Incubator-Gesundheitsberichte sind in diesem Checkout verfügbar?"
"Wie viele Podling-Gesundheitsberichte haben wir und wann wurden sie generiert?"
"Welche Podlings haben Gesundheitsberichte, die ich abfragen kann?"
"Über welche Gesundheitsmetriken und Berichtszeitfenster kann ich Informationen abrufen?"
"Zeige mir die Gesundheitszusammenfassung für Amoro."
"Was sagt der neueste Gesundheitsbericht über Iggy aus?"
"Finde Podlings mit Namen, die 'stream' enthalten, und fasse das beste Ergebnis zusammen."
"Zeige für diesen Podling die Gesundheitsmetriken der letzten 3 Monate."
"Zeige mir den ursprünglichen Markdown-Bericht für Amoro, damit ich die Quelle überprüfen kann."
"Vergleiche die Aktivität von Amoro über 3, 6 und 12 Monate."
"Verbessert oder verlangsamt sich die Entwicklungsaktivität von Iggy?"
"Vergleiche die aktuelle Mailinglisten-Aktivität mit dem langfristigen Trend für diesen Podling."
"Hat sich die PR-Merge-Aktivität dieses Podlings zwischen dem 3-Monats- und dem 12-Monats-Fenster verändert?"
"Verbessert oder verschlechtert sich der Bus-Faktor für diesen Podling über die Berichtszeitfenster hinweg?"
"Welche Podlings hatten in den letzten 3 Monaten die meisten Nachrichten in der Entwickler-Mailingliste?"
"Zeige mir Podlings ohne Commits in den letzten 3 Monaten."
"Welche Podlings haben die längste mediane PR-Merge-Zeit?"
"Erstelle ein Ranking der Podlings nach zusammengeführten PRs über das 6-Monats-Fenster."
"Finde Podlings mit geringer Reviewer-Diversität im aktuellen Berichtsfenster."
"Gib mir eine kurze Liste von Podlings, die aufgrund ihrer kürzlichen Aktivität möglicherweise die Aufmerksamkeit eines Mentors benötigen."
"Welche Podlings wirken bei Commits, PRs und Nachrichten in der Entwickler-Mailingliste ruhig?"
"Finde Podlings mit geringer kürzlicher Aktivität und vergleiche sie mit ihrem 12-Monats-Trend."
"Welche Podlings sollte ich manuell auf Bedenken hinsichtlich des Bus-Faktors oder der Reviewer-Diversität prüfen?"
Allgemeine Aufgaben sind über make verfügbar:
make format
make lint
make typecheck
make test
make coverage
make checkDieser Server fragt bereits generierte Berichtsdateien ab. Er führt nicht das Upstream-Sammlungsskript von Apache aus.
Der Arbeitsbereich hier enthielt kein lokales reports/-Verzeichnis, daher ist der Server so konzipiert, dass er jeden lokalen Klon oder eine kopierte Momentaufnahme des Apache-Berichtsverzeichnisses akzeptiert.
Compare one podling across two or three windows.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions 'compare' but doesn't specify whether this is a read-only analysis, if it requires specific permissions, what the output format is, or any rate limits. For a tool with zero annotation coverage, this is a significant gap in transparency about how the tool behaves operationally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a tool with no parameters and is front-loaded with the core action. Every part of the sentence contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations, no output schema, and 0 parameters, the description is incomplete for effective use. It doesn't explain what 'compare' entails (e.g., metrics compared, output format), behavioral traits, or usage context relative to siblings. For a comparison tool in a metric-focused server, more detail is needed to guide the agent adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't add parameter details, but since there are no parameters, this is acceptable. The baseline for 0 parameters is 4, as the description doesn't need to compensate for missing param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('compare') and target resource ('one podling across two or three windows'), which is clear but somewhat vague. It doesn't specify what aspects are compared or how the comparison is performed. However, it distinguishes from siblings like 'list_podlings' or 'get_window_metrics' by focusing on comparison rather than listing or retrieving metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for comparing podlings across windows, but doesn't mention prerequisites, when-not-to-use scenarios, or how it differs from siblings like 'query_metric_rankings' or 'search_podlings' that might involve podling analysis. This leaves the agent without clear contextual boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the raw markdown for one podling report.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns raw markdown but doesn't explain how the report is selected, if authentication is needed, potential errors, or response format details. This leaves significant gaps for a tool that likely involves data retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 retrieving a specific report (implied by 'one podling report'), no annotations, and no output schema, the description is incomplete. It doesn't explain how to specify which report, what the markdown contains, or error handling, leaving the agent with insufficient context for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, but that's acceptable here. A baseline of 4 is appropriate since the schema fully handles the lack of parameters without requiring compensation from 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?
The description clearly states the action ('Return') and resource ('raw markdown for one podling report'), making the tool's purpose understandable. However, it doesn't differentiate from sibling tools like 'get_report_summary' or explain what distinguishes 'raw markdown' from other report formats, preventing a perfect score.
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 no guidance on when to use this tool versus alternatives like 'get_report_summary' or 'search_podlings'. It lacks context about prerequisites, such as how to identify the specific podling report, or any exclusions, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get parsed metrics for one podling report.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a read operation ('Get') but doesn't disclose authentication needs, rate limits, error conditions, or what 'parsed metrics' entails (format, structure, or completeness). For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it immediately understandable without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a tool that presumably returns parsed metrics, the description is incomplete. It doesn't explain what 'parsed metrics' includes, how the podling report is identified, or the return format. For a tool in a metric-heavy context with multiple siblings, more detail is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description adds value by specifying the resource ('one podling report'), implying it operates on a single, implicitly identified report. This contextual meaning goes beyond the empty schema, justifying a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('parsed metrics for one podling report'), making the purpose understandable. It distinguishes from siblings like 'get_report_markdown' (which likely returns raw markdown) by specifying 'parsed metrics', but doesn't explicitly differentiate from 'get_window_metrics' or other metric-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_report_markdown', 'get_window_metrics', or 'list_metrics'. It doesn't mention prerequisites, context for 'podling report', or when this tool is preferred over other metric-retrieval options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return metrics for a single podling/window combination.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states what the tool returns without behavioral details. It doesn't disclose whether this is a read-only operation, potential errors, rate limits, or authentication needs, leaving significant gaps for a tool that likely queries metrics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with no wasted words. It is appropriately sized and front-loaded, making it easy to understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters and no output schema, the description is minimally adequate but lacks completeness. It doesn't explain what metrics are returned, their format, or error handling, which are important for a metrics query tool with no structured output documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by specifying that metrics are for a 'single podling/window combination', which clarifies the scope beyond what the empty schema provides, justifying a score above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'metrics for a single podling/window combination', making the purpose specific and understandable. It doesn't explicitly distinguish from siblings like 'list_metrics' or 'query_metric_rankings', but the focus on a single combination provides some implicit differentiation.
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?
No guidance is provided on when to use this tool versus alternatives. The description implies it's for a specific podling/window pair, but it doesn't mention prerequisites, when not to use it, or refer to sibling tools like 'list_metrics' for broader queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a high-level summary of the available Apache health reports.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool returns a summary but doesn't specify format, data freshness, rate limits, or authentication needs. This leaves critical operational details unclear for a tool that likely involves data retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters and no output schema, the description adequately covers the basic purpose. However, for a health reporting tool in a server with multiple related siblings, it lacks context on output format or how it complements other tools, leaving gaps in overall understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing on the tool's purpose instead, which aligns well with the schema's simplicity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Return') and resource ('high-level summary of available Apache health reports'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_report_summary' or 'get_report_markdown', which might offer similar functionality.
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 no guidance on when to use this tool versus alternatives like 'get_report_summary' or 'list_metrics'. It lacks context about scenarios where a high-level overview is preferred over detailed reports, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the supported metrics and windows for querying.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool returns data but doesn't disclose behavioral traits like whether it's a read-only operation, if it requires authentication, rate limits, or what the return format looks like (e.g., list, object). This leaves significant gaps for an agent to understand how to handle the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is minimally adequate but lacks depth. It doesn't explain the return values (e.g., structure of metrics/windows) or any behavioral context, which could be important for querying tools. However, the simplicity of the tool (0 params) means the description isn't severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate here, and it implies the tool takes no inputs, aligning with the schema. A baseline of 4 is given since no parameters exist and the schema fully covers them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return') and the target ('supported metrics and windows for querying'), making the purpose understandable. However, it doesn't explicitly differentiate this tool from its siblings like 'get_window_metrics' or 'query_metric_rankings', which appear related to metrics/windows, so it doesn't reach the highest score.
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 no guidance on when to use this tool versus alternatives. With siblings such as 'get_window_metrics' and 'query_metric_rankings' that might overlap in functionality, there's no indication of context, prerequisites, or exclusions for using 'list_metrics'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List podlings that have a parsed markdown report.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the filter condition ('have a parsed markdown report') but doesn't disclose behavioral traits such as pagination, rate limits, permissions needed, or what happens if no podlings meet the criteria. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any redundant information. It is appropriately sized and front-loaded, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 0 parameters, no annotations, and no output schema, the description is minimal but adequate for a simple listing tool. It specifies a filter condition, which adds some context, but lacks details on behavior, output format, or integration with siblings, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by specifying the filter condition ('have a parsed markdown report'), which provides context beyond the schema, though it doesn't detail how this filtering is applied internally.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('podlings'), specifying that they must 'have a parsed markdown report'. This distinguishes it from generic listing tools by adding a filter condition, though it doesn't explicitly differentiate from sibling tools like 'search_podlings'.
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?
No guidance is provided on when to use this tool versus alternatives like 'search_podlings' or other siblings. The description implies usage for podlings with parsed markdown reports but doesn't specify exclusions, prerequisites, or comparative contexts with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank podlings by one parsed metric for a specific window.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool performs ranking, which implies a read-only operation, but doesn't disclose behavioral traits like whether it requires authentication, has rate limits, returns paginated results, or what the output format looks like. This is inadequate for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Rank podlings') and adds necessary qualifiers ('by one parsed metric for a specific window') without any wasted words. It's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0 parameters, the description is incomplete. It lacks details on behavioral aspects like authentication needs, rate limits, or output format, and doesn't clarify how it differs from siblings. For a ranking tool with no structured data, this leaves significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds context by specifying 'by one parsed metric for a specific window', which implies inputs might be inferred from context or defaults, but since there are no parameters, a baseline of 4 is appropriate as it doesn't need to compensate for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Rank podlings by one parsed metric for a specific window', which provides a clear verb ('Rank'), resource ('podlings'), and scope ('by one parsed metric for a specific window'). However, it doesn't explicitly differentiate from siblings like 'get_window_metrics' or 'list_podlings', leaving ambiguity about when to use this versus those alternatives.
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?
No guidance is provided on when to use this tool versus alternatives. The description mentions ranking by a metric for a window, but it doesn't specify prerequisites, exclusions, or compare it to siblings such as 'get_window_metrics' or 'list_podlings', leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search podling names by case-insensitive substring.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the search is 'case-insensitive', which is useful, but fails to describe other critical behaviors like response format, error handling, or performance characteristics. This leaves significant gaps for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any redundant or unnecessary information. It is front-loaded and appropriately sized for its purpose, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic search action but lacks details on output format or behavioral context, making it minimally viable but with clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds value by specifying the search mechanism ('case-insensitive substring'), which is not captured in the schema, justifying a score above the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and resource ('podling names') with a specific constraint ('by case-insensitive substring'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'list_podlings', which could serve a similar listing function, preventing a perfect score.
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 no guidance on when to use this tool versus alternatives, such as 'list_podlings' for unfiltered listing or other search-related tools. It lacks context on prerequisites, exclusions, or typical use cases, offering minimal usage direction.
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.
v0.1.0compare_windowsget_report_markdownget_report_summaryget_window_metricshealth_overviewlist_metricslist_podlingsquery_metric_rankingssearch_podlingsScored across 9 tools
Each tool has a clearly distinct purpose with no overlap: compare_windows compares podlings across windows, get_report_markdown retrieves raw markdown, get_report_summary provides parsed metrics, get_window_metrics gives metrics for a single podling/window, health_overview offers a high-level summary, list_metrics enumerates supported metrics/windows, list_podlings lists podlings with reports, query_metric_rankings ranks podlings by metric, and search_podlings searches podling names. The descriptions unambiguously differentiate each tool's function.
All tools follow a consistent verb_noun or verb_adjective_noun pattern using snake_case: compare_windows, get_report_markdown, get_report_summary, get_window_metrics, health_overview, list_metrics, list_podlings, query_metric_rankings, and search_podlings. The naming is predictable and readable throughout, with no deviations or mixed conventions.
With 9 tools, the count is well-scoped for the Apache health reporting domain. Each tool earns its place by covering distinct aspects such as listing, retrieving, comparing, searching, and ranking podling health data. This is neither too thin nor too heavy, providing comprehensive functionality without bloat.
The tool surface offers complete coverage for querying and analyzing Apache podling health reports. It includes listing and searching podlings, retrieving raw and parsed report data, comparing across windows, getting metrics and rankings, and providing overviews. There are no obvious gaps; agents can perform full workflows from discovery to detailed analysis without dead ends.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
MCP server for medicaid-intelligence
MCP server for the Seline Analytics API
MCP server for Withings health data — sleep, activity, heart, and body metrics.
