The elmah.io MCP server allows AI assistants to interact directly with your error logs, deployments, and organization statistics. Debug production issues faster than ever before.
Scored across 23 tools
Each tool targets a distinct resource and action, with clear boundaries between list/get/detail and message state-changing operations. The paired reversible actions (fix/open, hide/unhide, bot/unbot) are explicitly described as opposites, so an agent can select correctly. No overlapping or indistinguishable tools stand out.
All tool names use consistent snake_case with a predictable resource_action or resource_get_details pattern. Variations like list_recent and list_frequent are still readable and consistent with the same convention. There is no mixing of camelCase or inconsistent verb styles.
At 23 tools, the server is on the heavy side for the stated error-monitoring scope. While most tools map to distinct resources or actions, the count sits in the borderline-heavy 16-25 range and could likely be consolidated with filtering parameters. Each tool is not clearly redundant, but the surface feels larger than necessary.
Core read and message-state operations are well covered, but there are notable gaps such as creating/updating/deleting logs, deployments, heartbeats, or uptime checks, and no general message search or filtered query tool beyond recent/frequent/count. Agents can work around some gaps using IDs and existing list tools, but full lifecycle coverage is missing.
List recent deployments for a log. A deployment represents a release of the software.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | How many recent deployments to return (default 5, max 25). | |
| logId | Yes | The ID (Guid) of the log to fetch deployments for. | |
| includeLogMessageMetrics | No | If true, includes metrics like new errors and severity counts for each deployment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are "recent" deployments and clarifies the deployment concept, but says nothing about ordering, recency window boundaries, or pagination/behavioral limits beyond what the schema already states.
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 short sentences, zero redundancy, and the core action is front-loaded before the domain definition. Every sentence earns its place.
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 list tool with full schema coverage and a complete annotation safety profile, the description provides enough to call it correctly. It only leaves ambiguous the meaning of "recent" relative to the count default, a minor gap given no output schema is needed here.
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 all three parameters (count with default/max, logId, includeLogMessageMetrics) are already fully documented in the schema. The description adds no parameter-level detail, so the baseline of 3 is correct.
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 recent deployments") plus a clear scope constraint ("for a log"), and even defines the domain term ("a deployment represents a release of the software"). It does not need sibling differentiation because there is no other deployments_* tool in the list, so a 4 is appropriate.
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 by the name and description – fetch deployment history for a given log – but there is no explicit when-to-use phrasing, prerequisites (e.g., that logId must reference an existing log), or exclusion notes. With no competing alternative tool, implied guidance is adequate but unremarkable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information and recent check-in history for a specific heartbeat.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| heartbeatId | Yes | The ID of the heartbeat. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds that the tool returns recent check-in history, which is useful return-behavior context, but it does not explain how much history, ordering, pagination, or any other operational nuance.
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 well-formed sentence with no filler and front-loads the action and resource. Every word earns its place.
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-only tool with full schema coverage and rich annotations, the description gives enough context to select and call it correctly, including a high-level statement of returned content. It falls short only in not clarifying what 'recent' means or how the history is structured, which is somewhat relevant because no output schema exists.
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?
Parameter schema coverage is 100%, and both logId and heartbeatId are documented directly in the schema. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.
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 resource (heartbeat) and scopes it to a specific heartbeat, clearly distinguishing it from the sibling heartbeats_list tool. It also states what the return includes: detailed information and recent check-in 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 phrase 'for a specific heartbeat' implies the tool should be used when the caller already has a heartbeat identifier, but there is no explicit when-to-use guidance, exclusion, or named alternative such as heartbeats_list. Usage must be inferred from the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all heartbeats configured for a log, including their current status.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that returned heartbeats include their current status; it says nothing about pagination, ordering, or what happens for a log with no heartbeats.
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 tight sentence with the resource and scope front-loaded and no filler. It is appropriately sized for a simple list tool, though it sacrifices some detail for brevity.
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 one-parameter read-only list operation with full annotation coverage and no output schema, the definition plus schema give enough to invoke it correctly. Only minor gaps remain around ordering/pagination and absent-result behavior.
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 logId parameter is fully documented in the schema as a Guid. The description's phrase 'configured for a log' merely restates that linkage, adding no syntax or format detail beyond the 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?
Specific verb+resource: lists heartbeats configured for a log and mentions it includes current status. It is reasonably distinguishable from the sibling heartbeats_get_details, though the description never explicitly contrasts the two.
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?
There is no when-to-use or when-not-to-use guidance. The sibling heartbeats_get_details exists and an agent has to infer the split (list vs. single-detail) from names alone, with no routing condition stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed configuration and metadata for a specific log.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log to fetch details for | |
| includeFilterDetails | No | If true, include log filters in output | |
| includeUptimeDetails | No | If true, include uptime checks in output | |
| includeHeartbeatDetails | No | If true, include heartbeats in output |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive, covering the safety profile. The description adds only that the output is 'configuration and metadata', without describing return shape, whether the include flags change behavior, or any access constraints.
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. It is efficient, though the brevity is partly why usage and behavioral context are thin.
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 detail fetch with full parameter coverage and no output schema, the description is minimally sufficient. It could do more to explain the include flags' effect on the response, but nothing critical is missing for a correct call.
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 all four parameters (logId and the three include flags) are already documented in the schema. The description adds no format, syntax, or flag semantics beyond that, 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?
States a specific verb (Get) and resource (detailed configuration and metadata for a specific log), so its function is unambiguous. It does not explicitly distinguish itself from the sibling logs_list, leaving the details-vs-list contrast to inference.
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?
There is no when-to-use guidance, no statement of prerequisites beyond the required logId, and no mention of the alternative logs_list or uptime_get_details siblings. The agent must infer that this is the single-item detail fetch.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of logs that the current user has access to.
| Name | Required | Description | Default |
|---|---|---|---|
| access | No | If set, only logs where the user has the specified access level configured are returned. Only applies when authenticated as a user, not an organization. | |
| favorites | No | If true, only return logs that the user marked as favorites. Only applies when authenticated as a user, not an organization. | |
| environment | No | If set, only logs with the specified environment name are returned |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the access-scoping fact, and says nothing about pagination, result limits, or ordering — acceptable given the annotation coverage but not enriching.
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 or redundancy. It is efficient, though its brevity is closer to under-specification than to tight, information-dense writing.
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 read-only list tool with complete schema coverage and full annotations, the description is minimally adequate. It omits any mention that filtering by access, favorites, or environment is possible, and gives no hint about result shape or volume, which an agent browsing logs would benefit from.
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 all three optional filters (access, favorites, environment) are already fully documented in the schema. The description adds no additional meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.
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 ('Get a list') and resource ('logs') with a permission scope ('that the current user has access to'). It is clearly distinguishable in kind from logs_get_details, though the description never names or contrasts with that sibling 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?
There is no explicit guidance on when to use this tool versus logs_get_details, nor any mention of the filtering axes (access, favorites, environment) that would tell an agent when this tool is the right choice. Usage can only be inferred from the word 'list'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark one or more log messages as bot-generated by ID. Only call this when the user has explicitly approved marking these specific messages as bot traffic — never speculatively while just investigating.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| messageIds | Yes | IDs of the messages to mark as bot (1-500 per call). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (destructive=true, idempotent=true, readOnly=false), and the description adds a real behavioral constraint those annotations cannot express: the operation requires explicit user approval before invocation. It does not describe reversibility (the messages_unbot sibling implies it) or the effect on downstream counts, but the approval gate is meaningful added context.
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, zero filler. The action is stated first and the approval precondition is front-loaded immediately after, so the critical constraint cannot be missed.
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 mutation tool with full schema coverage and annotations carrying the destructive/idempotent profile, the description supplies the one missing piece an agent must know: the human-approval precondition. Return behavior is unspecified, but no output schema exists and the caller mostly needs to know the operation succeeded, so this is minor.
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 both parameters (logId Guid, messageIds array), so the schema already documents them fully. The description only restates 'by ID' and 'one or more,' which duplicates what the schema provides without adding format, batching, or failure semantics.
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: 'Mark one or more log messages as bot-generated by ID.' The action is unambiguous and its inverse (messages_unbot in the sibling list) is easy to disambiguate from the name, but the description never names or contrasts that sibling 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?
Gives a clear when-to-use condition ('only when the user has explicitly approved marking these specific messages') and an explicit when-not ('never speculatively while just investigating'). It stops short of routing to alternatives such as messages_unbot or messages_fix, but the gating condition is unusually concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count the number of log messages based on severity and timeframe.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | From date (default 90 days ago). | |
| logId | Yes | The ID (Guid) of the log. | |
| query | No | Full-text or Lucene query. Available fields: applicationName, browser, category, country, detail, hidden, hostName, isBot, isBotSuggestion, isBurst, isFixed, isNew, message, messageTemplate, method, os, remoteAddr, severity, source, statusCode, time, type, url, user, userAgent, version. Example: browser:chrome || statusCode:500 || url:*\/api\/* && message:"NullReferenceException" | |
| hidden | No | Whether to include hidden log messages. Defaults to false, matching the default search behavior in the UI. | |
| severity | No | Optional severity filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds no behavioral context beyond the annotations: no note on return shape (a number), cost, limits, or how the count interacts with hidden messages.
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 that states the action and its scoping dimensions with no filler. It is appropriately sized, though it omits useful detail rather than being 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?
For a read-only aggregate with fully documented parameters and annotations covering safety, the description is minimally adequate. With no output schema, the description could state that it returns a count, and it should help distinguish this tool from the many listing siblings, which it does not.
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%, with all five parameters including query syntax, hidden-message handling, and date defaults documented in the schema. The description only echoes severity and timeframe, adding no syntax or semantics beyond what the schema already provides, 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 states a specific verb and resource (count log messages) and even names the two main filters (severity, timeframe). However, it does not distinguish this tool from the many sibling messages_* tools such as messages_list or messages_list_frequent, so an agent cannot route between them from the description alone.
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?
There is no indication of when to prefer counting over listing (messages_list, messages_list_recent, messages_list_frequent), nor any prerequisite or exclusion guidance. The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a log message as fixed by ID. Only call this when the user has explicitly asked to mark this error as fixed — never speculatively while just investigating errors.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| messageId | Yes | The ID of the message to fix. | |
| markAllAsFixed | No | If true, also marks every other message with the same grouping hash as fixed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, destructive, idempotent operation, so the safety profile is covered structurally. The description adds the behavioral caution against speculative invocation, which is useful, but it does not disclose the scope-expanding side effect of the markAllAsFixed parameter. With annotations carrying the mutation severity, a 3 is appropriate.
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 tight sentences with zero filler. The core action is front-loaded and the caution follows immediately; every clause earns its place.
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 an agent must infer return behavior, but the description plus the annotations and fully-covered schema give enough to invoke it correctly. The only modest gap is the implications of markAllAsFixed, which the schema already explains.
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 all three parameters including markAllAsFixed are documented in the schema itself. The description adds no syntax or behavioral detail about them, 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 states a specific verb and resource: 'Mark a log message as fixed by ID,' which tells an agent exactly what mutation occurs and on which entity (identified by logId/messageId). It is clear enough to distinguish from read-oriented siblings like messages_get or messages_list_recent, though it does not explicitly contrast with adjacent mutators such as messages_hide or messages_open.
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 explicit when-to-use and when-not-to-use guidance: only call when the user has explicitly asked to mark an error as fixed, and never speculatively while investigating. That is a real constraint agents otherwise get wrong. It stops short of naming an alternative tool for speculative investigation, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single log message by ID. Includes full details like stack trace and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| fields | No | Comma-separated list of fields to include in the response. Use this to save tokens by only requesting what's needed. Available fields: HostName, Type, Message, MessageTemplate, Time, StatusCode, Source, Detail, Severity, Url, Method, ClientIp, User, Version, Application, Hidden, UserAgent, Browser, Os, IsNew, IsFixed, IsBot, IsBotSuggestion, Country, AssignedTo, CorrelationId, Domain, Category, All. Enriched fields (require blob storage lookup, only include when explicitly needed): SourceCode, Sql, Breadcrumbs, Form, QueryString, ServerVariables, Data. | |
| messageId | Yes | The ID of the message. |
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 a return-content hint (stack trace and metadata), which is useful given there is no output schema, though it stops short of describing detail levels, cost, or error behavior for a missing ID.
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 short sentences, front-loaded with the verb and scope. The second sentence is slightly padded ('like metadata') but is justified because no output schema exists to convey what is returned.
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-item fetch with strong annotations, the essentials are present: what it returns and that it targets one record. Missing is any differentiation from logs_get_details and any statement about behavior when the messageId is not found, which matters since no output schema exists.
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 logId, messageId, and the fields parameter are already fully documented in the schema, including the token-saving advice and enriched-field caveats. The description adds nothing beyond 'by ID', so the baseline of 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 (Fetch) and resource (a single log message) scoped by ID, which cleanly separates it from list-style siblings like messages_list and messages_list_recent. It does not, however, differentiate itself from the similarly named logs_get_details, which an agent could easily confuse it with.
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?
There is no explicit guidance on when to use this tool versus alternatives such as messages_list, logs_get_details, or messages_list_recent. The 'by ID' phrasing implies single-item retrieval, but no when-to-use or when-not-to-use conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hide a log message by ID. Only call this when the user has explicitly asked to hide this message — never speculatively while just investigating errors.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| messageId | Yes | The ID of the message to hide. | |
| markAllAsHidden | No | If true, also hides every other message with the same grouping hash. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation profile is covered by structured data. The description adds a policy gate against speculative calls, but says nothing about reversibility (messages_unhide exists) or the blast radius of markAllAsHidden beyond same grouping hash.
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, zero waste, and the core action is front-loaded ahead of the conditional caution. Every clause earns its place.
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 destructive single-target mutation with no output schema and rich annotations, the description covers purpose, trigger condition, and a misuse warning. It could be more complete by noting the operation is reversible via messages_unhide and that markAllAsHidden affects sibling messages.
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 all three parameters, including the markAllAsHidden grouping-hash behavior, are already documented in the schema. The description adds no parameter-level meaning, which makes the baseline 3 the correct score.
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 (hide a log message, by ID), which is immediately distinguishable from the sibling messages_unhide. It does not explicitly name the alternative, but the opposing verb makes the distinction self-evident.
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 a clear when-to-use condition tied to explicit user intent, plus an explicit when-not-to-use exclusion (never speculatively while investigating errors). It stops short of naming sibling alternatives such as messages_fix or messages_unhide for non-hiding cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify the most frequent/common error groups in a log. Great for finding 'noisy' bugs.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Search to this date. | |
| from | No | Search from this date. | |
| count | No | Number of groups to return (1-25). | |
| logId | Yes | The ID (Guid) of the log. | |
| query | No | Full-text or Lucene query. Available fields: applicationName, browser, category, country, detail, hidden, hostName, isBot, isBotSuggestion, isBurst, isFixed, isNew, message, messageTemplate, method, os, remoteAddr, severity, source, statusCode, time, type, url, user, userAgent, version. Example: browser:chrome || statusCode:500 || url:*\/api\/* && message:"NullReferenceException" | |
| fields | No | Comma-separated list of fields to include in the response. Use this to save tokens by only requesting what's needed. Available fields: HostName, Type, Message, MessageTemplate, Time, StatusCode, Source, Detail, Severity, Url, Method, ClientIp, User, Version, Application, Hidden, UserAgent, Browser, Os, IsNew, IsFixed, IsBot, IsBotSuggestion, Country, AssignedTo, CorrelationId, Domain, Category, All. | |
| hidden | No | Whether to include hidden log messages. Defaults to false, matching the default search behavior in the UI. | |
| severity | No | Filter by severity. | Error |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe, idempotent, non-destructive read operation (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the safety profile is covered. The description adds that results are aggregated into 'groups', but does not explain how groups are formed, ranked, or whether similar messages are collapsed, leaving meaningful behavioral detail unstated.
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 short, well-formed sentences with the core purpose front-loaded and the finding-the-useful hint at the end. No wasted words.
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 100% schema coverage and annotations covering the safety profile, the definition is largely sufficient for invocation. The only minor gap is that it does not hint at the shape of the returned groups (e.g., group plus occurrence count), though no output schema exists to compensate.
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 fully documents all 8 parameters, including count range (1-25), date filters, Lucene query fields, and severity. The description contributes no additional parameter meaning, 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?
States a specific verb and resource: it identifies the most frequent/common error groups in a log, which is more specific than a generic list. However, it does not differentiate itself from the sibling messages_list_recent or messages_count, so an agent must infer the distinction between 'frequent' and 'recent' grouping.
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 phrase "Great for finding 'noisy' bugs" implies a use case, but there is no explicit when-to-use/when-not guidance or named alternative among siblings like messages_list_recent. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most recent log messages for a specific log.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Search to this date. | |
| from | No | Search from this date. | |
| count | No | Number of messages (1-100). | |
| logId | Yes | The ID (Guid) of the log. | |
| query | No | Full-text or Lucene query. Available fields: applicationName, browser, category, country, detail, hidden, hostName, isBot, isBotSuggestion, isBurst, isFixed, isNew, message, messageTemplate, method, os, remoteAddr, severity, source, statusCode, time, type, url, user, userAgent, version. Example: browser:chrome || statusCode:500 || url:*\/api\/* && message:"NullReferenceException" | |
| fields | No | Comma-separated list of fields to include in the response. Use this to save tokens by only requesting what's needed. Available fields: HostName, Type, Message, MessageTemplate, Time, StatusCode, Source, Detail, Severity, Url, Method, ClientIp, User, Version, Application, Hidden, UserAgent, Browser, Os, IsNew, IsFixed, IsBot, IsBotSuggestion, Country, AssignedTo, CorrelationId, Domain, Category, All. | |
| hidden | No | Whether to include hidden log messages. Defaults to false, matching the default search behavior in the UI. | |
| severity | No | Filter by severity: Verbose|Debug|Information|Warning|Error|Fatal. | Error |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful ordering and scoping context (most recent, specific log), but it omits notable behavioral details such as the default severity filter of Error and the default count limit, which affect what is 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?
The description is a single front-loaded sentence with no wasted words. It efficiently states the operation and scope without padding.
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 core action is covered, and the rich input schema documents all parameters. However, for an 8-parameter list tool with many siblings and no output schema, the description does not help route among alternatives or disclose key behavioral defaults like the Error severity filter.
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 all eight parameters, including query syntax, fields, severity, and date range, are already documented in the schema. The description adds no parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate.
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 (list) and resource (log messages) with scope qualifiers (most recent, for a specific log). It is clear enough to distinguish from count/get-style siblings, but it does not explicitly name or differentiate from messages_list_frequent or other list 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?
There is no when-to-use guidance, no exclusions, and no mention of alternatives such as messages_list_frequent or messages_get. The implied context is only that this lists recent messages, leaving the agent to infer selection from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reopen a fixed log message by ID — the opposite of messages_fix. Only call this when the user has explicitly asked to reopen this message — never speculatively while just investigating errors.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| messageId | Yes | The ID of the message to open. | |
| markAllAsOpen | No | If true, also opens every other message with the same grouping hash. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by framing the operation as the inverse of messages_fix and warning against speculative invocation. It does not describe what state changes on reopen or the blast radius of a rollback.
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 action and the anti-speculation guard both front-loaded. Every clause carries information an agent needs.
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?
A three-parameter mutation tool with no output schema, but annotations carry the safety profile and the schema fully documents the parameters. The description covers purpose and invocation discipline; only the post-reopen state effect is 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 coverage is 100%, so logId, messageId, and markAllAsOpen (including the grouping-hash semantics) are already documented in the schema. The description adds no parameter-level meaning, which is acceptable but earns only 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?
Specific verb ('Reopen') plus resource ('a fixed log message by ID'), and it explicitly positions itself as the inverse of the sibling messages_fix. An agent can distinguish it from messages_fix, messages_hide, and messages_unhide 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?
Gives an explicit when-to-use condition ('Only call this when the user has explicitly asked to reopen this message') and an explicit when-not ('never speculatively while just investigating errors'). This is the strongest form of routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unmark one or more log messages as bot-generated by ID — the opposite of messages_bot. Only call this when the user has explicitly asked to undo a bot marking.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| messageIds | Yes | IDs of the messages to unmark as bot (1-500 per call). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds the reversal relationship to messages_bot and a caution against proactive use, but does not describe what state changes or what happens to non-matching IDs. Modest added value over 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?
A single front-loaded sentence stating the action, scope, and sibling relationship, plus one short usage constraint. No filler; every clause earns its place.
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-required-parameter mutation tool with full schema coverage and a rich annotation set, the description supplies the essential safety guidance (only on explicit user request). It is nearly complete; return behavior is not described, but no output schema exists and the sibling messages_bot covers the mirror operation.
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%: logId is defined as a Guid and messageIds documents the 1-500 range. The description only echoes 'by ID' and 'one or more', adding no meaning beyond the schema, 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?
States a specific verb ('unmark') and resource ('log messages as bot-generated'), and explicitly differentiates itself from the sibling messages_bot by calling itself 'the opposite of messages_bot.' An agent can distinguish it from all siblings without opening a 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?
Adds an explicit gating condition: 'Only call this when the user has explicitly asked to undo a bot marking.' This tells the agent when to use it, and the sibling reference points to the reverse operation. It stops short of enumerating alternatives or exclusions beyond that one rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unhide a previously hidden log message by ID — the opposite of messages_hide. Only call this when the user has explicitly asked to unhide this message — never speculatively while just investigating errors.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| messageId | Yes | The ID of the message to unhide. | |
| markAllAsUnhidden | No | If true, also unhides every other message with the same grouping hash. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the mutation/idempotency profile is covered. The description adds genuinely new context beyond them: the tool only applies to messages in an already-hidden state and should be invoked on explicit user request only, which is behavioral guidance the annotations cannot convey. It stops short of disclosing side effects such as the bulk unhide path or how the message state changes afterward.
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. The purpose and the sibling relationship are front-loaded, followed by the usage constraint; every clause carries distinct information.
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 three-parameter mutation tool with no output schema and full schema coverage, the description supplies purpose, sibling disambiguation and an explicit consent guardrail. What's missing is any note on the consequences of unhiding or of the bulk flag, which would matter given destructiveHint=true.
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 logId, messageId and the markAllAsUnhidden flag are fully documented in the schema. The description only echoes 'by ID' and adds no syntax, format, or guidance for the bulk flag, 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?
States a specific verb (unhide) plus resource (a previously hidden log message) and its key input (by ID). It explicitly positions itself against a sibling, 'the opposite of messages_hide', so an agent can distinguish it from the hide/get/list tools without opening a 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?
Gives an explicit when-to-use rule with a hard exclusion: 'Only call this when the user has explicitly asked to unhide this message — never speculatively while just investigating errors.' This is exactly the kind of guardrail an agent needs to avoid inadvertently reversing a deliberate hide, and it names the sibling it mirrors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about an organization including configuration, subscription, usage statistics, and more.
| Name | Required | Description | Default |
|---|---|---|---|
| includeUsage | No | If true, include usage statistic for the current month (log messages, emails, etc.). | |
| organizationId | Yes | The ID of the organization. |
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 useful content about what is returned (configuration, subscription, usage statistics) but says nothing about whether includeUsage changes response size, latency, or payload shape. Adequate but shallow given annotations carry the safety story.
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?
One front-loaded sentence with no filler; the resource and verb lead. It is efficient, though the trailing 'and more' is slightly vague padding that could have been trimmed.
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 usefully previews the returned fields (configuration, subscription, usage statistics), which is what an agent needs to decide whether to call it. It stops short of covering pagination or auth prerequisites, but for a simple two-parameter read tool it is close to complete.
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 both parameters are already documented in the schema, including includeUsage's boolean semantics and current-month scope. The description's mention of 'usage statistics' loosely aligns with includeUsage but adds no syntax or format detail beyond the schema. 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 (Get) and resource (organization details) and enumerates the categories of data returned (configuration, subscription, usage statistics). It is clear on its own, but it never distinguishes itself from the sibling organizations_list, so an agent must infer the singular-vs-list split from the name alone.
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?
There is no when-to-use guidance, no stated prerequisites (e.g. needing an organizationId obtained from organizations_list), and no mention of the sibling it complements. The agent is left to infer that this is the single-entity counterpart to organizations_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all organizations that the current user is a part of. When authenticated as an organization, the current organization is returned.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is handled. The description adds meaningful context beyond them: the result set varies by authentication mode, collapsing to just the current organization when authenticated as an org. It does not describe ordering or pagination, 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?
Two short sentences with zero waste; the core purpose is front-loaded and the authentication nuance follows immediately. Every sentence earns its place.
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-only list tool with no output schema, the definition covers purpose and the auth-dependent result set adequately. It does not state the returned fields or whether the list is ordered, but annotations and the absence of an output schema make that a minor 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?
The tool takes zero parameters, so there are no parameter semantics to document and the baseline of 4 applies. Nothing in the description is needed or missing on this dimension.
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 (get a list) and resource (organizations) with an explicit scope qualifier ('that the current user is a part of'). It is clearly distinguishable from organizations_get_details by the list-vs-single nature, though it never names that 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?
It implies when the tool applies via the auth-mode note ('When authenticated as an organization, the current organization is returned'), but gives no explicit when-to-use vs alternatives or guidance to prefer organizations_get_details for a single org's details. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details about a single recommendation for a log or an organization. Specify exactly one of logId or organizationId.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | No | The ID (Guid) of the log the recommendation belongs to. Mutually exclusive with organizationId. | |
| organizationId | No | The ID of the organization the recommendation belongs to. Mutually exclusive with logId. | |
| recommendationId | Yes | The ID of the recommendation to fetch. |
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 the safe-read profile is fully covered by structured data. The description adds the selector constraint (one of logId/organizationId), which is useful, but discloses nothing about return shape or error 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?
Two short sentences, front-loaded with the purpose before the parameter constraint. Nothing is wasted and no filler remains.
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?
Low complexity, one required parameter, full schema coverage, and annotations carrying the safety profile mean the agent has nearly everything needed. The only missing element is what 'details' actually returns, which is unstated and there is no output schema to fall back on.
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 both scope parameters and recommendationId are already documented with their mutual exclusivity. The description restates that same exclusivity without adding format or behavioral detail beyond the schema, which is the expected 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?
States a specific verb ('Get details') and resource ('a single recommendation'), with scope narrowed to a log or organization. This clearly separates it from recommendations_list, though it does not explicitly name that sibling as an alternative.
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 instruction to specify exactly one of logId or organizationId is a genuine usage constraint, but it is a duplicate of the schema's own 'mutually exclusive' notes rather than guidance about when to reach for this tool instead of recommendations_list or logs_get_details. Usage is implied by the get/details naming convention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of recommendations for a log or an organization. Recommendations are automated suggestions for improving error monitoring setup, security, and configuration. Does not include the description and suggestions fields; call recommendations_get_details for those. Specify exactly one of logId or organizationId.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | No | The ID (Guid) of the log to fetch recommendations for. Mutually exclusive with organizationId. | |
| state | No | Only recommendations with this state are returned. | Open |
| organizationId | No | The ID of the organization to fetch recommendations for. Mutually exclusive with logId. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds a non-obvious payload trait — that the description and suggestions fields are omitted from results — which the annotations do not convey. It stops short of covering pagination or result limits.
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, front-loaded with the core action before the exclusions and the parameter constraint. The final sentence largely restates the schema's mutual-exclusivity note, a minor redundancy, but overall there is little wasted text.
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 partially compensates by describing what the result set excludes. It omits the state parameter's filtering behavior and any pagination/volume expectations, but for a simple read-only list tool with 100% schema coverage the gaps are small.
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 both logId and organizationId already carry descriptions including their mutual exclusivity, which the description merely restates. The description does not mention the state filter or its default of 'Open', so it adds no meaning beyond the schema. 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 states a specific verb and resource ('Get a list of recommendations') and scopes it to 'a log or an organization'. It explicitly differentiates itself from the sibling recommendations_get_details, which is the closest competing tool, so an agent can choose 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?
It names the alternative tool and the exact condition that selects it ('Does not include the description and suggestions fields; call recommendations_get_details for those'), plus a hard invocation constraint ('Specify exactly one of logId or organizationId'). Nothing about routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Getting system information like current date and time. Use this when calculating time intervals, etc.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 fully covered by structured data. The description adds only that the result includes current date/time; it says nothing about format, timezone, or other fields, which is a modest addition over the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences that get to the point immediately. The trailing 'etc.' is filler and slightly weakens precision, but overall it is compact and easily scanned.
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-param, no-output-schema tool the description covers the essentials, but 'system information like current date and time' with 'etc.' leaves the actual contents ambiguous, and nothing clarifies return shape or timezone. Adequate but with a clear gap for an agent that needs to know what it will receive.
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 convey; baseline 4 applies. The description does not misrepresent any inputs.
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 clear verb ('Getting') and resource ('system information'), and names a concrete example ('current date and time') that matches the tool name system_get_context. It stops short of enumerating the full return payload (the 'etc.' leaves scope fuzzy) and offers no sibling differentiation, but no sibling overlaps this concern.
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 one usage trigger ('when calculating time intervals'), which implies context, but provides no when-not guidance and names no alternatives. With a sibling set of unrelated list/get tools, there is little routing ambiguity, so implied usage is acceptable but thin.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the latest real-time results for a specific uptime check, including regional performance metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. | |
| checkId | Yes | The ID (Guid) of the uptime check. |
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 that results are "real-time" and include "regional performance metrics," which hints at the payload, but says nothing about freshness windows, rate limits, or failure 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?
A single well-formed sentence with the verb and resource front-loaded and no filler. Every clause carries information.
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-required-parameter read tool with full annotation coverage and no output schema, the description covers the core scope and hints at returned metrics. It stops short of defining what "latest" means time-wise, but nothing essential for invocation 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 100% – both logId and checkId are documented as Guids. The description adds no meaning beyond the schema (e.g., relationship between logId and checkId), 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?
States a specific verb ("Fetches") and resource ("latest real-time results for a specific uptime check") and mentions the content returned (regional performance metrics). This distinguishes it from the sibling uptime_list, though it does not name that sibling 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?
Usage is implied by "a specific uptime check" – the agent infers this needs a concrete checkId rather than a listing call. However, there is no explicit when-to-use vs uptime_list guidance, no prerequisites, and no exclusions, so guidance remains inferential.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all uptime checks for a log, including their current status and 24h up/down percentage.
| Name | Required | Description | Default |
|---|---|---|---|
| logId | Yes | The ID (Guid) of the log. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds the returned content (status, 24h up/down percentage), which is genuinely useful given there is no output schema, but says nothing about pagination, result size limits, or behavior for unknown logIds.
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?
One sentence, front-loaded with the verb and resource, with zero filler. Every clause (list, scope, payload summary) earns its place.
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 single-parameter read tool whose annotations already establish safety and idempotency, the description covers what is returned, which matters because no output schema exists. Missing only edge-case behavior (empty results, invalid logId, pagination), so it is nearly complete.
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% (logId is documented as the log's Guid), so the schema already carries the parameter meaning. The description only restates "for a log" and adds no format, validation, or error semantics beyond that. Baseline 3 is correct here.
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 a list of all uptime checks for a log") and even previews the payload (current status, 24h up/down percentage). The list-vs-details split with uptime_get_details is implied by the wording but never named explicitly, 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?
The scope ("for a log") implies when to reach for this tool, but there is no explicit when-to-use/when-not guidance and no mention of the natural alternative, uptime_get_details, for per-check questions. Adequate but gap-laden.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current user details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 safety profile is fully covered. The only added context is the word 'current', which implies the result depends on the authenticated caller's session rather than a supplied identifier — a useful but slight hint beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the verb and resource front-loaded and no wasted clauses. The only quibble is the filler word 'details', which conveys nothing specific.
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 trivial no-arg read this is the minimum viable text, and the annotations carry the safety profile. However, no output schema exists, so the description is the only place that could indicate what user fields come back, and it says only 'details' — an agent cannot predict the payload shape.
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 and schema coverage is 100%, so there is nothing for the description to clarify. This is the baseline for a no-parameter tool; no parameter meaning is missing.
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?
Names a specific verb and resource ('Fetch the current user details'), and the 'current user' scoping makes it unambiguous even without sibling differentiation — no other sibling operates on users. It stops short of 5 only because it never contrasts itself with related lookups like organizations_get_details or system_get_context.
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?
There is no when-to-use guidance, no stated prerequisites, and no named alternative. The use case is simple enough to be inferred, but the description provides no routing signal at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
