MCPulse

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

The description goes well beyond the annotations by disclosing important behavioral constraints: admins cannot act on owners, the last owner cannot be demoted, and an ownerless account cannot be administered. These are exactly the kind of edge-case and authorization traits an agent needs before calling a mutating 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 compact and front-loaded: the core action comes first, followed immediately by the critical constraints. Every sentence earns its place, with no filler or repetition of schema content.

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 role-change tool with full schema coverage, an output schema, and annotations indicating mutation without destruction, the description provides all necessary context. The ownership and admin restrictions are the key contextual details an agent needs, and they are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters already have clear, detailed descriptions in the schema. The tool description itself adds little parameter-level meaning beyond the word 'promote or demote', 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 clearly states the action with 'Promote or demote someone', which combined with the title makes the tool's purpose unambiguous. However, it does not explicitly compare against sibling tools like invite_member or remove_member, so it stops short of full sibling 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?

The intended usage is implied: use this when you need to change a member's role. It does not explicitly state when to prefer this over invite_member or remove_member, nor does it state when not to use it, aside from the ownership constraints. The 'Call list_members if unsure' guidance is helpful but appears only in the parameter schema.

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

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

The description adds meaningful behavioral context beyond the readOnly/destructive annotations: the alert is checked nightly against the previous day, requires admin or owner privileges, and only fires on days with enough calls in scope. It also uses the min_calls example to clarify the statistical guardrail, and the channels parameter description discloses that only in_app delivery actually sends today while others are queued. This is transparent about timing, permissions, and side effects.

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 three sentences long, with the core purpose front-loaded in the first sentence. Every sentence earns its place: the first defines the behavior, the second covers permissions and schedule, and the third uses a concrete example to explain the min_calls constraint. There is no fluff or redundancy.

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

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

For a tool with 9 parameters, 6 required, annotations, and an output schema, the description plus the rich schema descriptions are complete enough for an agent to invoke it correctly. It covers permissions, the nightly evaluation model, the noise floor, and even directs the agent to list_alerts for metric units and list_mcps for MCP identification. The output schema covers return values, and the behavioral details are sufficiently disclosed.

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 baseline is 3. The main description adds a clarifying example for min_calls ('two empties out of three calls is 67% and means nothing'), which is helpful, but it does not systematically explain every parameter. The heavy lifting is correctly left to the schema, including units, comparator direction, channel behavior, and tool/client narrowing.

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 action: watch one metric on one MCP and alert when it crosses a threshold. This clearly distinguishes create_alert from its siblings like update_alert, delete_alert, and list_alerts. The purpose is immediately understandable and not a tautology of the name.

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 gives useful context such as 'Admin or owner' and the nightly check, and the metric parameter tells the agent to call list_alerts first for unit guidance. However, it never explicitly says when to use create_alert versus update_alert or delete_alert, so the agent must infer that this tool is for creating a new alert rather than modifying or inspecting one.

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

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

The description transparently explains the tool's behavior: it returns the created MCP with its id, does not create an ingest key, and cannot mint keys. This goes beyond a simple 'creates a resource' statement and sets accurate expectations about the result and limitations.

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 two concise sentences that deliver essential information without redundancy. It is well-structured and easy to parse.

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 description covers the input, the return value (MCP with id), and a key caveat (no ingest key, dashboard directions). This provides sufficient context for a user to understand the tool's purpose and limitations.

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 fully describes the 'name' parameter with a clear example. The description does not add extra meaning beyond the schema, so it falls at the baseline for parameter 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 verb 'Add' clearly specifies creating a new MCP server, and the description distinguishes it from sibling tools like list_mcps, get_mcp, rename_mcp, and delete_mcp. The purpose is unambiguous.

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 offers practical guidance by noting that no ingest key is created and directing the user to the dashboard for key generation. It lacks an explicit mention of when to use this tool versus alternatives, but the function is distinct enough that the context is clear.

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

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

Beyond the destructiveHint annotation, it discloses that recorded firings are deleted while already-delivered notifications remain, and warns about the alternative non-destructive action.

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 compact, front-loaded with permission and effect, and includes the alternative in a single additional sentence without unnecessary detail.

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 delete operation, the description covers permission, side effects, and the alternative action. No important context is missing given the output schema is not relevant to invocation.

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 already fully documents alert_id as 'Which rule to delete. From list_alerts.' and the description adds no additional parameter-level detail beyond that.

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 tool deletes an alert and specifies the required admin or owner role. It distinguishes itself from update_alert by noting when to use that 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?

Explicitly instructs to use update_alert with enabled: false when the intent is only to stop notifications, providing clear decision guidance.

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

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

While the annotations already mark this as destructive, the description adds significant behavioral detail: it enumerates the full cascade (keys, events, rollups, sessions), states irreversibility and unrecoverability, and instructs the agent to confirm with the user. This goes well beyond the annotation's boolean destructiveHint.

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, all of which carry essential information. The scope is stated first, followed by the irreversibility warning and the user-confirmation requirement. There is no filler or redundant restatement of the tool name or schema.

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

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

For a tool with one required parameter, a complete schema, rich annotations, and an output schema, the description covers all critical behavioral aspects. The agent knows exactly what will be deleted, that it is irreversible, and that user confirmation is needed before invocation.

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 already fully describes the single 'mcp' parameter at 100% coverage, including matching semantics and a fallback suggestion to list_mcps. The description does not add new parameter-level meaning, 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 ('Delete') and resource ('an MCP'), and immediately clarifies scope by enumerating what is deleted ('keys, events, rollups and sessions'). It clearly differentiates this from sibling tools like get_mcp, create_mcp, and rename_mcp by emphasizing the destructive, exhaustive nature of the operation.

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 makes the intended use clear: it is for the irreversible removal of an MCP and all associated data. It adds an explicit operational guideline to confirm with the user first, but it does not explicitly name alternatives or state when not to use this tool. Nevertheless, sibling context makes the appropriate use obvious.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered by structured metadata. The description adds some context by indicating the response includes the person's role, but it discloses no additional behavioral traits such as authentication assumptions, scoping to the current user, or any side effects.

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 compact phrase with no filler. It front-loads the core resource ('The account') and adds the role detail efficiently, so 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?

With no parameters and a rich output schema, the description is largely complete for a simple read-only lookup. The only minor gap is that 'this person' is not explicitly defined as the current authenticated user, but the tool name and zero-parameter schema make that a reasonable inference.

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 zero parameters, so there is little for the description to add about parameters. The phrase 'this person' implies the account refers to the current user, which is useful context given the absence of any identifier parameter.

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 identifies the resource as the account the person belongs to and includes their role, which adds useful specificity beyond the title. It partially distinguishes from siblings like get_company and get_profile by framing the result as an account membership rather than a company or profile, though the tool's verb is only in the name.

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 given about when to use this tool versus alternatives. The description does not mention get_company, get_profile, or list_members, nor does it explain whether this is the current user's account or another member's account.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds substantial behavioral context beyond that: the 'delivers' field is framed as 'the honest answer' with the warning that only in-app actually sends while the rest queue with no draining job, webhook URLs are never returned and webhook_hint is masked intentionally, and fan-out semantics differ by scope (personal = once per recipient, shared = once per firing). This is exactly the kind of non-obvious behavior a caller must know.

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 longer than average but every sentence carries distinct information with no filler: inventory, scope semantics, delivery honesty, security masking, then exclusions. The logical ordering is strong, and the length is justified by the subtlety of the domain. Minor deduction for the indirect opening line, which delays the concrete subject.

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 tool takes zero parameters and has an output schema, so the remaining burden is conceptual — and the description covers everything: the four-channel model, why scope matters for delivery behavior, the misleading 'delivers' field, the webhook masking constraint, and where excluded data (thresholds, digest) lives. Nothing an agent needs to invoke or interpret this tool correctly 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?

With zero parameters, the baseline is 4, and the description exceeds it by defining the semantics of the returned concepts: 'scope' as the distinguisher, 'delivers' as the truthful send-status indicator, and 'webhook_hint' as a masked identifier. An agent can correctly interpret the response rather than misreading fields like 'delivers' as actual delivery.

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 never uses an explicit retrieval verb ('returns', 'lists'), but it exhaustively characterizes the resource — the four channels, their scopes, and the Slack/Discord connections — making the purpose unmistakable. It also distinguishes itself from siblings by exclusion, stating that thresholds and the weekly digest are not here. The metaphorical opening ('Where anything the product wants to tell this person goes') is informative but less direct than a standard verb+resource formulation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to alternatives: 'Per-tool thresholds are not here, and neither is the weekly digest... see list_alerts and get_digest.' It names both siblings and the reason they exist elsewhere (they require a scope). An agent knows exactly when this tool is the wrong choice and which sibling to select instead.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds a useful behavioral nuance beyond annotations: timezone is display-only and metrics are bucketed in UTC, preventing incorrect assumptions about timezone-driven 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 two short sentences with no filler. The core purpose is stated first, and the important timezone caveat follows immediately.

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

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

For a zero-parameter, read-only tool with an output schema available, the description is nearly complete: it names the data returned and flags the one important semantic caveat. It only lacks explicit sibling differentiation, which is more a usage-guidance concern.

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 zero parameters, so there is no parameter documentation burden on the description. Baseline 4 applies because there is nothing for the description to add beyond what the empty schema already communicates.

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 identifies the resource as 'the account's company details,' which matches the tool name and title. It is not vague, but it does not explicitly differentiate this getter from sibling tools like get_account or get_profile.

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 guidance on when to use get_company versus other getter tools such as get_account or get_profile. The timezone caveat implies some context, but no alternatives, exclusions, or conditions are stated.

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

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

Annotations already establish read-only and idempotent behavior. The description adds useful context beyond those annotations: each subscribed MCP sends its own digest, so multiple subscriptions produce multiple digests, and nothing is sent when this tool is used. This clarifies both semantics and side-effect-free 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 compact and well-structured. It front-loads the core question, then adds the per-MCP digest behavior in a second sentence. Every sentence adds value and nothing redundantly repeats the schema or annotations.

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-only tool with an output schema, the description covers the query target, the channel dimension, and the fact that nothing is sent. It does not enumerate the possible channels or explicitly identify the person, but these are reasonably left to the output schema and system context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already explains that mcp can be a name or id, matching is case-insensitive, and list_mcps can be used for disambiguation. The tool description adds no parameter-specific meaning beyond what the schema provides, 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?

The description clearly identifies the resource (one MCP) and the query intent: whether the person is subscribed to the weekly digest and through which channels. It does not use an explicit verb like 'retrieves' or 'returns', but the title and the read-only query phrasing make the purpose clear enough.

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 'Whether...' phrasing implies this tool is for checking subscription state, and 'Nothing sends yet' signals it is a safe read. However, the description does not explicitly name the obvious alternative set_digest or state when to use one versus the other.

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

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

Annotations already mark the tool as read-only and idempotent, so the description's job is lighter. It adds useful behavioral context: results are newest-first, include an unread count, and are per-person because channel acceptance can differ even within the same team. This goes beyond what the schema or annotations reveal.

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 two short sentences with no wasted words. The first sentence front-loads the resource, ordering, and unread count; the second explains why the data is per-person. Both sentences earn their 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 low-complexity tool with one optional parameter and an output schema, the description is largely sufficient. The main gaps are that it does not explicitly name whose inbox is returned (current user is implied) and does not point to related sibling tools, but these are minor given the available structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the only parameter, unread_only, is fully described in the schema. The description does not add meaningful parameter semantics beyond mentioning unread count, so the baseline 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 identifies a specific resource — 'this person's in-app alert deliveries' — and gives two key characteristics: ordering ('newest first') and an unread count. It stops short of a perfect 5 because it never explicitly contrasts with siblings like list_alert_firings or mark_inbox_read, though the resource is fairly distinct.

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 about when to use get_inbox versus alternatives such as mark_inbox_read or list_alert_firings. The 'per person' note hints that this tool is user-scoped rather than team-wide, but no exclusions or alternative conditions are stated.

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

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

Annotations already establish read-only and idempotent behavior. The description adds context beyond that by revealing the output format ('sentences with numbers'), the scope of diagnostic rules, and a recommendation to run it multiple times to isolate per-client problems. No contradictions with annotations exist.

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 compact and front-loaded, with each paragraph earning its place. The first paragraph gives purpose and the second gives a use pattern. Minor vagueness ('when a rule fires') and slightly awkward grammar keep it from being flawless, but it is not bloated.

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 an output schema present, the description does not need to explain return values. It covers the diagnostic scope, usage context, and a strategy for per-client investigation. The only noticeable gap is leaving 'when a rule fires' undefined, but the rest of the definition is sufficiently complete for correct invocation.

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?

Input schema descriptions cover 100% of the parameters, so the baseline is met. The description's mention of running 'once unfiltered, then once per client' adds mild usage context for the clients parameter, but it does not add substantial meaning beyond what the schema already documents.

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 tool diagnoses server health through five named problem categories ('low first-call success, heavy payloads, silent empty results, dead tools, slow tools') and is explicitly distinguished from retrieving a specific figure. The odd phrasing still conveys a specific verb+resource purpose and separates it from siblings like get_usage and get_overview.

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 explicitly says when to use this tool: 'when the user asks how their server is doing rather than for a specific figure.' It also provides a concrete usage strategy ('Worth running twice when a rule fires: once unfiltered, then once per client') and refers the agent to get_overview for per-client context, giving clear operational guidance.

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

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

Annotations already establish read-only and idempotent behavior. The description adds useful behavioral context by narrowing the response to name and creation time and by stating that numeric data is intentionally not included. This goes beyond the annotations without contradicting them.

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 two short, purposeful sentences. It front-loads the core return scope and then immediately directs the agent to the relevant alternative for other data needs. There is no filler or redundancy.

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

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

This is a simple, single-parameter read tool with strong annotations, a well-described schema, and an output schema present. The description covers what the tool returns, what it excludes, and which sibling handles the excluded case. Nothing essential is missing for correct selection and invocation.

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 description for the mcp parameter is already strong: it explains name-or-id matching, case-insensitivity, and suggests list_mcps when unsure. With 100% schema coverage, the tool description does not need to repeat parameter details. The description adds no new parameter semantics, 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 clearly identifies the verb and resource: it gets one MCP and specifies the exact return scope (name and creation time). It also distinguishes itself from get_overview by explicitly pointing numeric requests to that sibling, which prevents confusion even without reading other schemas.

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 gives an explicit alternative and condition: 'For its numbers, use get_overview.' This tells the agent when to switch tools. It does not explicitly contrast with list_mcps, though the singular 'One MCP' and the schema's guidance to call list_mcps when unsure cover that gap indirectly.

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

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

With readOnlyHint and idempotentHint annotations already covering safety, the description adds useful behavioral details: omitting metrics returns summary figures, and larger series like daily, tools, clients, follows, and sparklines are only returned when explicitly named. It also communicates the cost-conscious behavior of returning exactly what is requested.

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 compact, front-loads the core purpose, and every sentence earns its place. The first sentence establishes what the tool returns; the second gives actionable usage guidance without redundancy or filler.

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 output schema and full parameter coverage, the description is largely complete for correct invocation: it explains the default return behavior, how to request specific metrics, and what larger series are available. It does not add explicit sibling differentiation or mention edge behavior beyond parameters, but nothing critical is missing for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters thoroughly, so the baseline is 3. The description goes beyond the schema by explaining the selective-return behavior, giving a concrete example (metrics: ["calls"]), and warning against pulling the full overview unnecessarily. This adds meaningful guidance for using the metrics parameter correctly.

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 identifies the tool as returning headline metrics for one MCP over a date range and enumerates the specific metrics included. It does not explicitly name or compare against sibling tools like get_usage or get_insights, so it misses the strongest form of differentiation, but the scope and metric list make the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (when you need headline metrics for a single MCP over a date range) and provides concrete guidance on requesting only needed metrics. However, it does not explicitly explain when to choose this tool over its get_* siblings or state any exclusions, leaving some selection guidance to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by specifying exactly what is returned—name and email—and clarifying that the data belongs to the signed-in person, which goes 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?

The description is a single, front-loaded sentence that conveys the essential information without wasted words. It is appropriately sized for a zero-parameter, read-only profile retrieval tool.

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, zero parameters, read-only/idempotent annotations, and existing output schema, the description is fully complete. Nothing an agent needs to invoke this tool correctly 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?

The tool has zero parameters, so there is nothing for the description to explain about inputs. The schema fully covers the empty parameter set, and the description adds no unnecessary parameter information.

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 that the tool returns the signed-in person's own name and email, which is a specific verb-resource combination. It distinguishes this profile retrieval from sibling tools like get_account or get_company by emphasizing 'signed-in person's own'.

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 clear context that this tool is for the current user's own profile data. It does not explicitly mention alternatives or exclusions, but the scope is clear enough to select it over sibling get_* tools.

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

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

The readOnly and idempotent annotations already cover side effects, so the description does not need to repeat that. It does disclose the counting rule (start time) and implies a default limit through the schema. No hidden side effects or pagination behavior is mentioned, but that's adequately handled by the output schema and parameter descriptions.

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 two sentences and reasonably concise. The first sentence is slightly awkward ('Sessions in range with calls, bytes and cost per session, plus the most recent ones') but conveys the essential idea without unnecessary fluff. It trades a small amount of clarity for brevity, which is acceptable.

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 presence of a complete output schema and per-parameter descriptions, the tool description provides enough context for an agent to invoke it correctly. It explains the counting semantics and hints at the recent-session feature. It does not explicitly specify sorting order (e.g., most recent first), but the 'limit' parameter description implies recency, so this is a minor omission.

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 covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds the key nuance that sessions are counted by start time, which affects interpretation of the date-range parameters (from, to, last_days). It also reinforces the 'clients' guidance already given in the schema. No parameter description conflicts with 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?

The description states the tool returns sessions in a date range with per-session metrics (calls, bytes, cost) and mentions a 'most recent' aspect. It differentiates from aggregated tools like get_overview by emphasizing session-level detail and start-time counting, though 'Sessions in range' is slightly ambiguous about the exact response shape.

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 a direct usage hint for the 'clients' parameter, instructing the agent to read get_overview first to identify per-client splits. It also clarifies the counting semantics (by start time vs. per day), which helps distinguish this tool from day-summarizing alternatives. However, it does not explicitly contrast with get_usage or get_digest.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds real behavioral context beyond annotations: it always returns results broken out per client, and it provides diagnostic meaning for the first-call success metric. This helps the agent interpret results, not just invoke 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 tight and front-loaded: the first sentence states exactly what the tool returns, and the second paragraph explains how to interpret a key metric. There is no filler, and the diagnostic guidance earns its place rather than padding the 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?

Given the presence of a rich output schema, 100% parameter coverage, and read-only/idempotent annotations, the description is complete. It explains the tool's scope, the guaranteed per-client breakdown, and the interpretation guidance an agent needs to use the result effectively. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all six parameters including format, constraints, and semantics. The description does not add new parameter-level detail, but it also does not need to; it stays at the level of what the tool returns. Baseline 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 opens with 'One tool in detail' and enumerates a concrete set of metrics: outcome breakdown, latency distribution, retries, first-call success, response size, and co-called tools. This clearly identifies the resource and the specific analytical angle, distinguishing it from siblings like list_tools (which lists tools) and get_overview (which is broader).

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 gives actionable guidance: read the per-client breakdown first when first-call success looks low, and explains that a model-specific failure indicates a description problem rather than a server problem. It also points to get_overview for the per-client split and list_mcps for resolving names. It does not explicitly say 'do not use this tool for X', but the context is clear enough.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds the specific categories of usage returned, but does not disclose potential behavioral details such as whether usage values are live or cached.

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

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

A single sentence front-loads the core concept and uses a dash to succinctly list the key components. There is no filler or redundant phrasing.

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 tool with an output schema and read/idempotent annotations, the description plus structural metadata is fully sufficient. An agent can invoke the tool correctly without any ambiguity.

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 no parameters, so the schema fully covers parameter semantics. The description correctly has nothing to add here, warranting the baseline score of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource ('account usage') and the purpose ('what the account is using against its plan'), with concrete examples: MCPs, events, team size. It is distinct enough from siblings like get_account and get_overview, though it does not explicitly name 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?

The description implies the tool is for retrieving plan consumption details, giving context for when to use it. However, it gives no explicit when-not-to-use guidance or references to alternative get_* sibling tools.

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

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

The description goes beyond the annotations by explaining immediate effects (status becomes 'invited'), future effects (becomes 'active' on first sign-in), and edge cases (re-inviting a pending invite refreshes it, re-inviting an active member is refused). This gives the agent valuable expectations for side effects and failure modes, while the annotations already note it is not read-only or destructive.

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 compact and front-loaded with the core purpose, then covers status transitions and the important name requirement in just a few sentences. Every sentence earns its place, and it avoids unnecessary detail.

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 description, combined with the rich schema and annotations, covers the purpose, parameter semantics, side effects, and edge cases. With no unresolved ambiguity, the agent has everything needed to invoke the tool correctly and predict its consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful guidance for 'full_name' by explaining why it matters (otherwise the team list shows an address) and for 'email' by explaining re-invite behavior. This enriches the semantics beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Add someone to the account by email'), the resource, and the result, distinguishing it from sibling tools like remove_member and change_member_role. It also explains the invited vs active status, which clarifies exactly what the tool does.

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 explains when to use the tool (to invite a new user by email) and implies the alternative context, e.g. changing an existing member's role would use change_member_role. It doesn't explicitly mention when not to use it or name alternatives, but the context is clear enough.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond those annotations: results are newest first, rendered as sentences, and facts are frozen at fire time so renaming or deleting a rule does not rewrite history. This is meaningful behavioral transparency.

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 two terse sentences that front-load the core purpose, scope, ordering, and output format, then add an important retention behavior. There is no filler or repetition of schema details.

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 annotations, a 100%-covered input schema, and an output schema, the description is sufficiently complete. It explains what is returned, the ordering, the per-MCP scope, and a subtle historical behavior that an agent could not infer from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters are already well documented in the input schema, including the mcp name/id matching behavior and the default limit of 50. The description adds only minor semantic context, such as 'on one MCP' and 'newest first,' which reinforces but does not significantly extend what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb plus resource: it lists alert firings for one MCP, newest first, as sentences. It also clarifies that these are firing history records, not the alert rules themselves, which helps distinguish it from sibling tools like list_alerts without naming them directly. It stops short of an explicit sibling comparison, so it does not fully earn 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 'on one MCP' implies the intended use case: retrieve firing history for a specific MCP. However, the description does not explicitly state when to use this tool versus alternatives such as list_alerts, nor does it mention any exclusions or contexts where another tool is preferred.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description goes beyond this by warning about the metric catalogue being the only source of units, adding the actionable caution that a threshold in the wrong unit 'silently never fires.' This is valuable behavioral context that annotations alone do not provide.

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 compact and front-loaded, first describing the tool's output, then adding a meaningful warning. Every sentence earns its place; the language is direct and avoids filler. It reads well for an agent scanning tool descriptions.

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 description fully covers the tool's purpose, the scope of the single parameter, the key output elements, and a non-obvious pitfall. With an output schema present, the description does not need to detail return structure. Nothing essential is missing for selecting and invoking this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the single 'mcp' parameter with coverage at 100%, including case-insensitive matching and a pointer to list_mcps. The description adds context that alerts are scoped to 'one MCP' and that the metric catalogue is also returned, but this is not essential parameter-level detail. The baseline of 3 applies because 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?

The description names a specific resource ('alert rule') and states exactly what is returned: the sentence, last fired time, frequency, and channels. It also clearly distinguishes itself from the sibling tool list_alert_firings by describing the alert rules themselves rather than the firing history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage context: 'Read this before creating a rule.' This tells the agent when the tool is important. It does not explicitly name alternative tools or state when not to use it, but the guidance about the metric catalogue is a strong, clear signal for when this tool is necessary.

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

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

The description adds important behavior beyond the readOnly/idempotent annotations: the raw key is hashed and never returned, and only the identifying prefix is exposed. This is non-obvious, security-relevant context that an agent needs before invoking or relying on the response.

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 two short clauses with no filler. It front-loads the resource and returned fields, then adds the critical hashed-key caveat in the second sentence. 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 single-parameter, read-only list operation with an output schema and read-only/idempotent annotations, the definition is complete. The description covers what is returned and what is not, and the schema covers how to specify the MCP.

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 description itself does not discuss the `mcp` parameter, but the input schema fully documents it: by name or id, case-insensitive, with a pointer to list_mcps if unsure. Since schema description coverage is 100%, the baseline of 3 applies and the description need not compensate further.

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 identifies the resource ('an MCP's ingest keys') and the exact fields returned (name, prefix, created, revoked), so the purpose is clear. It lacks an explicit verb and does not distinguish itself from siblings like revoke_key, but the title and tool name supply the action.

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 context is clear: this is the tool for viewing ingest keys belonging to a given MCP. The parameter schema adds helpful guidance to call list_mcps if unsure, but the description itself provides no explicit when-not-to-use or alternative-selection guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description's safety burden is low. It adds useful behavioral context by specifying the account-wide scope and the performance data returned, which goes beyond what the annotations convey.

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 two sentences with no filler. The first sentence front-loads what is returned and the second gives a clear usage trigger, 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?

For a zero-parameter, read-only listing tool with an output schema, the description is complete. It covers the resource scope, the included metrics, and the situations that should trigger 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 zero parameters, so there is no parameter documentation burden. With 100% schema coverage and no parameters, the description appropriately focuses on output scope and usage rather than argument 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?

The description clearly identifies the operation as listing every MCP server on the account, including the 30-day call stats and first-call success metric. The scope 'Every MCP server on this account' distinguishes this from sibling get_mcp, which targets a single server.

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 explicitly states when to use the tool: 'Start here when the user names a server you have not seen, or asks what they have.' It gives clear context for invocation, though it does not explicitly name alternatives or when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by explaining that invited members appear as member rows without users and are not separate entities. This helps the agent correctly interpret list results and avoid confusion.

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 deliver the core purpose and the key semantics of the invited status. No filler exists, and the most important scope information ('Everyone in the account') appears first.

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

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

For a parameterless, read-only listing tool with an output schema and clear annotations, the description covers all essential context: what is listed, who is included, and what invited status means. Nothing needed to invoke it correctly 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?

The tool has zero parameters and the schema coverage is 100%, so there is nothing extra the description needs to explain about parameters. It appropriately doesn't invent parameter guidance where none is needed.

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 tool lists everyone in the account, including invited but not-yet-signed-in members. It uses a specific verb ('list') and resource ('members'), and the invited-status explanation distinguishes it from member mutation tools like invite_member and remove_member. The scope is unambiguous.

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 clearly conveys when to use this tool: when you need the full set of account members, not just active users. It does not explicitly name alternatives or state when not to use it, but the sibling context makes the distinction obvious since all other member-related tools perform mutations.

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

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

Annotations already declare readOnlyHint and idempotentHint, so no side-effect disclosure is needed. The description adds useful behavioral context by specifying exactly what kind of aggregate data the table contains and that it is scoped to one MCP, going beyond the bare 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 sentences with no wasted words: the first defines the output and scope, the second gives the usage workflow and the sibling alternative. The key information is front-loaded.

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

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

With an output schema present, rich per-parameter schema descriptions, and annotations covering read-only and idempotent behavior, the description is complete for an agent to select and invoke the tool correctly. The workflow guidance and metric list fill the remaining gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already has meaningful descriptions, so the description does not need to repeat parameter semantics. The prose adds only a high-level hint that the table is scoped to one MCP, but no additional parameter-level meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the resource (every tool on one MCP), the specific metrics returned (calls, first-call rate, average response size, p95 latency, schema size), and frames it as a tool-health table. It also distinguishes itself from get_tool by saying to use get_tool once you know which tool is the problem.

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 gives explicit usage guidance: use this tool to find which tool is the problem, then use get_tool once you know. This directly routes an agent to the correct alternative at the right stage of the workflow.

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

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

The description states the direct effect (clearing unread count) and the scope (all-or-nothing). It does not explicitly mention every potential side effect, but the all-or-nothing phrasing and the contrast with individual marking make the behavior sufficiently clear.

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 concise, using two short sentences that convey purpose, scope, and rationale without extraneous detail.

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 description fully covers what the tool does and why it is designed that way. Since an output schema is present, return-value details are not required. No important context 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?

There are no parameters to describe, and the schema coverage is complete. No additional parameter guidance is needed.

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 ('Clears the unread count') and the title identifies the inbox as the target. It also distinguishes this tool from dashboard-based individual marking by emphasizing the all-or-nothing behavior.

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 explicitly explains when to use this tool versus the dashboard: it is deliberately all-or-nothing over MCP, while individual-id marking is relegated to the dashboard. This gives clear guidance without ambiguity.

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

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

Annotations already indicate a destructive operation, and the description adds useful behavioral context: the member loses access to every MCP in the account, and unaccepted invitations can be withdrawn. This goes beyond the raw annotation flags without contradicting them.

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 convey the main action, the invitation edge case, and the key consequence. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a simple single-parameter destructive tool with an output schema and full schema coverage, the description is complete. It tells the agent what happens, who is affected, and when the invitation path applies. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single parameter fully, including the accepted formats (email or member id) and a pointer to list_members for disambiguation. The description adds no additional parameter-level meaning, 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?

The description uses a specific verb and resource ('remove someone from the account') and clearly distinguishes the invitation-withdrawal case from removing an active member. This differentiates it from sibling tools like invite_member, change_member_role, and delete_mcp.

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 clear context for when to use the tool: removing an existing member or withdrawing an unaccepted invitation. It does not explicitly name alternatives or exclusions, but the two explicit use cases give enough guidance for an agent to select it appropriately.

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

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

Annotations already indicate this is a write operation that is not destructive, but the description adds valuable detail: the id, keys, and data are untouched. This clarifies the exact mutation scope beyond what readOnlyHint/destructiveHint convey.

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 that states the action first and then the critical non-effect. Every phrase earns its place with no redundancy.

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

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

For a simple two-parameter rename operation with a complete input schema, output schema, and safety annotations, the description covers everything an agent needs: what changes, what stays the same, and how to identify the target MCP.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters are individually documented with meaningful guidance (case-insensitive matching, max length, no history). The tool description adds no additional parameter semantics, 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?

The description uses a specific verb and resource ('Change an MCP's display name') and sharply scopes the operation by stating that only the display name changes. This clearly distinguishes it from sibling tools like create_mcp, delete_mcp, and get_mcp.

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 makes it clear this is for renaming an existing MCP's display name, and the line 'Nothing else about it moves' communicates what this tool is not for. It does not explicitly name alternative tools, but the context is strong enough for an agent to select it correctly.

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

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

This is the standout dimension. The description discloses a critical side effect beyond what annotations declare: 'the SDK swallows the failure, so nobody gets an error, the data simply stops.' This tells the agent that revocation is silent and consequence-bearing, which is exactly the behavioral context needed for both invocation and communication with the user. It complements the destructiveHint=true annotation rather than merely repeating it.

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, each earning its place: the core action, the behavioral consequence, and the caution. The most important information is front-loaded, and there is zero filler or repetition of the title.

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 destructiveHint annotation and presence of an output schema, the description covers what matters most: the immediate effect, the silent failure mode, and a warning to verify the target key. The only minor gap is that it never explicitly states whether revocation is reversible or what to do if the wrong key is revoked, though 'Be sure which key it is' strongly implies irreversibility.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters in detail, including how to identify a key ('by its `mp_live_…` prefix or its id') and an mcp ('matched case-insensitively'). The description adds no parameter-level information, which is acceptable given the baseline of 3 when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair ('Stop a key working, immediately'), which unambiguously states what the tool does. It is clearly distinguished from siblings like list_keys and list_mcps, which read or list rather than revoke. The title reinforces the same action without redundancy.

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 establishes a usage context: this is the tool to use when you want to immediately disable an ingest key. It implies a precondition ('Be sure which key it is') suggesting prior verification before invocation. However, it never explicitly names an alternative or states when not to use this tool; the guidance to consult list_keys/list_mcps lives in the schema parameter descriptions, not the description itself.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=false; the description adds the important behavioral context that this only changes the caller's own notification choice and grants no new data access ('numbers they are already allowed to look at'). It doesn't describe post-subscription effects such as confirmation or delivery timing, but those are reasonably covered by the schema's channel description.

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 two short sentences with no filler; the key permission/scope constraint is front-loaded and the second sentence clarifies that this is about notifications on already-visible data. Every sentence adds information not present in the title or schema.

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

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

For a tool with a rich input schema and output schema, the description covers the non-obvious permission and scope aspects, which are the main things an agent could not infer. The only real gap is the lack of explicit routing guidance such as 'check get_digest to see current subscription' or 'do not use for team-level changes'.

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 input schema already documents mcp, channels, and subscribed thoroughly, including defaults and the fact that channels are ignored when unsubscribing. The description's 'choosing what they receive' adds only a light thematic gloss rather than semantic 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?

The title explicitly says 'Subscribe or unsubscribe from a digest' and the description adds that the operation is scoped to the caller's own subscription ('set their own'), so the action and resource are clear. It does not explicitly contrast with sibling tools like get_digest, but the title alone distinguishes them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an implied usage context: anyone with read access to the MCP may change their own digest ('Anyone who can read the MCP may set their own'), which signals a self-service action. It never states when to prefer this over get_digest or create_alert, nor when not to use it.

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

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

With readOnlyHint=false and destructiveHint=false already present, the description adds valuable behavior beyond the annotations: omitted fields are left untouched, disabling preserves history and allows re-enabling, and this is a non-destructive alternative to deletion. This gives the agent an accurate mental model of side effects.

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 compact and front-loaded: permission, partial-update behavior, a concrete example, and the deletion trade-off are all in three sentences. Every sentence earns its place and there is no redundant filler.

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 very rich input schema, output schema, and annotations, the description is sufficient for an agent to select and invoke the tool correctly. It covers the key behavioral nuance (partial update), permission, and the main alternative. It intentionally leaves parameter-level details to the schema, which is appropriate 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?

The schema already provides 100% parameter coverage with rich descriptions, so the baseline is 3. The description adds meaning beyond the schema by explaining the PATCH-like semantics: omitted fields are left alone, and a single-field call like { alert_id, enabled: false } is sufficient. This directly informs how parameters should be provided.

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 makes clear that this tool modifies an existing alert/rule, highlighting the partial-update behavior and the specific silencing use case. It distinguishes itself from delete_alert by noting history survives. It does not restate the full range of updatable fields, but the title and example are unambiguous.

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 states the permission prerequisite ('Admin or owner') and gives explicit guidance to prefer this tool over deleting when history preservation matters. It also shows how to perform a minimal one-field update. It does not explicitly contrast with create_alert, but the naming and context make that distinction obvious.

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

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

The description goes beyond the raw annotations: it explains the merge behavior (sending one channel cannot switch the other off), the global silencing semantics of setting a channel to false, and the interaction with alert rules. This is valuable behavioral context that the annotations alone (readOnlyHint=false, destructiveHint=false) do not convey.

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 well-organized into three concise paragraphs: what the tool does, the behavioral consequence, and the exclusion for Slack/Discord. Every sentence carries meaningful information, and the most important behavior (merge) is front-loaded.

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

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

For a single-parameter update tool with a rich output schema and complete schema coverage, the description fully covers what an agent needs: scope, merge behavior, silence semantics, exclusions, and the relationship to alert rules. Nothing is missing for correct invocation.

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 already has 100% coverage and a rich description of the channels parameter. The tool description reinforces the key semantics (merge, not replace) and the delivery model, but the schema itself is already strong, so the description adds moderate extra value.

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 it updates a person's personal channel preferences (in-app and email) with a specific merge behavior, distinguishing it from account-level connections. It names the sibling get_channels and the broader family of update_* tools implicitly by being explicit about what it does.

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 explicitly explains when to use this tool (updating a person's channel preferences) and when not to (Slack/Discord are account-level, admin-only, dashboard). It also explains the relationship to alert rules, giving clear context for when this tool is the right half of the delivery mechanism.

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

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

The annotations already mark this as a write operation (`readOnlyHint: false`). The description adds partial-update semantics and the null-clears-a-field behavior, and calls out that `name` is only settable here. It does not cover authorization or side effects, but the basic safety profile is present.

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

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

Two sentences with no filler. The verb and resource come first, followed by the two most important behavioral rules. 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 7-parameter update with no required fields and an output schema, the description covers the essentials: patch semantics, null-clearing behavior, and the unique role of `name`. It is not exhaustive about permissions or alternative tools, but nothing critical is missing for making 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?

Since schema coverage is 100%, each parameter is already documented, but the description adds cross-parameter meaning: omitted fields are left unchanged while null clears a field. It also highlights `name`'s special uniqueness. This meaningfully supplements 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?

The description uses a specific verb ('Change') with a clear resource ('company details') and adds a distinctive constraint: `name` can only be set here. This separates it from siblings like `update_profile` and `get_company`, though it does not explicitly name 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?

It gives explicit call-time guidance: only include fields meant to change, and null clears a field. It does not state when not to use this tool or name alternatives explicitly, but the context is clear enough for an agent to select it for company detail changes.

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

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

The annotations only indicate that the operation is not read-only and not destructive. The description adds crucial behavior: every field is optional and omitted fields are untouched, passing null for full_name clears it rather than omitting it, and theme cannot be null because 'system' represents following the OS. These details go well beyond what the annotations provide.

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 concise sentences deliver purpose, update semantics, and the null-vs-omit distinction without redundancy. The most important usage rule is stated up front, and every sentence earns its place. It is tightly structured and immediately actionable.

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 optional-field update tool with an output schema, the description fully covers what an agent needs: what the tool does, which fields exist, how optionality works, the special null behavior for full_name, and the meaning of the 'system' theme. No critical behavioral gap remains.

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 well. The description adds value by summarizing the shared optionality rule and explicitly distinguishing null from omission for full_name, which reinforces and generalizes the schema descriptions. It does not introduce new parameter-level details not present in the schema, hence a 4 rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Set or clear your own name, or change your dashboard theme.' It clearly identifies the two distinct operations and states that it operates on the caller's own profile, which distinguishes it from sibling tools like update_company or change_member_role.

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 'your own name' and 'dashboard theme' establishes clear usage context for self-profile updates, and the optional-field semantics clarify how to perform partial updates. However, it does not explicitly name alternatives or state when not to use this tool, such as for changing other members' roles, so it falls just short of a 5.

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