Polar MCP

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them by asserting it does not call the Polar API and does not expose secrets, which is a meaningful assurance for an install/guidance endpoint.

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

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

Two short sentences, front-loaded with the positive scope followed by the negative guarantee. Nothing is wasted.

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

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

An output schema exists, so return-value explanation is unnecessary, but the two input parameters are undocumented in both schema and description, and the tool's relationship to the overlapping guidance siblings is left implicit. Adequate but with clear 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?

Both parameters (client and response_format) have 0% schema description coverage, and the description mentions neither. With enums present but no documented meaning or effect of choosing e.g. 'claude' vs 'generic', or markdown vs json, the description fails to compensate for the coverage gap.

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 as machine-readable install/runtime/client guidance, which is more specific than the name alone, but it never states plainly what the tool returns or how it differs from close siblings like polar_quickstart, polar_capabilities, or polar_onboarding. An agent cannot tell from the text why it would pick this over those.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the many sibling tools (quickstart, capabilities, onboarding) that plausibly overlap with this one. The only guidance is a negative statement about what it does not do.

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=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description usefully adds that the cache is optional and toggled by environment variables, but says nothing about the shape of the returned status or failure modes.

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

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

Two short sentences with zero filler, and the core purpose is front-loaded before the configuration detail. 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 simple read-only status check with an output schema present, the description covers what the tool reports and how the underlying cache is enabled. The only real gap is the undocumented response_format parameter.

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

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

Schema description coverage is 0% for the single parameter, response_format, and the description never mentions it. The enum values (markdown/json) are largely self-explanatory, but the description does nothing to compensate for the documentation gap.

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

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

States a specific verb ('Show') and resource ('local SQLite cache status'), making the read-only diagnostic nature clear. It doesn't explicitly distinguish itself from similar status siblings like polar_connection_status or polar_capabilities, but the 'cache' qualifier is specific enough to separate it from the data-listing tools.

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

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

The second sentence explains how to enable the cache (POLAR_CACHE=sqlite or POLAR_CACHE=true), which implicitly tells the agent this tool is for checking cache enablement, but gives no explicit when-to-use or when-not-to-use guidance versus other status tools. Usage is inferable rather than stated.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's bar is lower. It adds that the output covers privacy boundaries and recommended workflow, which is useful content scope, but says nothing about auth requirements, rate limits, or whether it is a zero-argument informational call.

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

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

A single front-loaded sentence with no filler; the four content areas are listed efficiently. It is appropriately terse for a simple informational 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?

With an output schema present, return-value detail is not required, and annotations carry the safety profile. For a no-required-parameter informational tool the description is adequate, though it could note that no arguments are needed and how it relates to sibling discovery tools.

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

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

Schema description coverage is 0%, so the description is expected to compensate, yet it never mentions response_format or its markdown/json enum. The enum and default are self-descriptive in the schema, but the description adds no meaning whatsoever beyond structured fields.

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

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

States a specific verb (Explain) and enumerates the resource scope: supported Polar data, privacy boundaries, agent workflow, and project links. It is clear what the tool returns, but it does not differentiate itself from closely related meta siblings such as polar_data_inventory, polar_agent_manifest, or polar_quickstart.

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 call this versus the many overlapping meta/onboarding siblings (polar_data_inventory, polar_agent_manifest, polar_quickstart, polar_demo). The description implies it is a discovery entry point but names no alternative or triggering condition.

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 readOnly/idempotent/non-destructive safety, but the description adds genuinely new behavioral facts: it does not call the Polar API and does not expose secrets, which matters for a config-auditing tool and is not derivable from the annotations.

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

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

A single dense sentence that front-loads the verb and the scope, with the key constraint ('without calling Polar or exposing secrets') trailing appropriately. No wasted sentences, though the item list is long enough to be slightly heavy.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description covers what is inspected and the no-API-call guarantee; the only real gap is the unaddressed parameter semantics.

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

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

Schema description coverage is 0%, and the description never mentions the two parameters (client and response_format) despite 'optional MCP client readiness' hinting at client. With two undocumented enum parameters, the description fails to compensate for the coverage gap, leaving the agent to infer parameter meaning from enum values alone.

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 ('Check') and enumerates the concrete resources inspected (local config, token file, Node version, privacy mode, cache readiness, optional MCP client readiness). This distinguishes it from siblings like polar_cache_status and polar_privacy_audit, though the distinction is implied by scope overlap rather than stated outright.

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 'without calling Polar' implies this is a pre-flight/diagnostic check, which cues usage, but the description never states when to prefer it over polar_capabilities, polar_cache_status or polar_privacy_audit, nor any exclusions. Usage is inferable but not spelled out.

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=true, idempotentHint=true, and destructiveHint=false, so 'Read-only' largely restates structured data. The genuinely additive disclosure is 'non-medical', which frames the output as not clinical advice, plus 'when available' signalling graceful degradation when some data sources are missing. That is useful but thin for an aggregating 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?

Two short sentences with no filler, and the purpose is front-loaded before the read-only/non-medical caveat. Efficient, though arguably it errs slightly toward under-specification rather than conciseness.

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

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

An output schema exists, so return-value explanation is rightly omitted. However, for an aggregation tool spanning four data domains with no required parameters, the description does not clarify behavior when one or more domains are empty, nor default lookback interaction — leaving gaps an agent would reasonably want covered.

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 67%, with days and timezone documented in-schema and response_format left without a description. The description adds no parameter-level detail at all, so with coverage above the midpoint the baseline of 3 applies.

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

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

States a specific verb ('Build') and resource ('daily summary') and enumerates the source data domains: sleep, activity, Nightly Recharge, and training. It is clearly distinguishable from polar_weekly_summary by scope, though the description never names that sibling explicitly to sharpen the contrast.

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

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

There is no when-to-use guidance, no named alternative (e.g. polar_weekly_summary, polar_wellness_context), and no stated preconditions such as required auth or connected device. The phrase 'when available' hints that source data may be absent but does not tell the agent when to prefer this tool over the list_* siblings.

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 cover the safety profile (readOnly, idempotent, closed-world, non-destructive). The description adds genuinely new behavioral context that annotations cannot express: it makes no Polar API calls and exposes no user data, clarifying its local/static nature. It stops short of describing how fresh or exhaustive the inventory is.

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

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

Two tight sentences: purpose first, non-goals second. Every clause earns its place with no 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?

An output schema exists, so return values need no explanation, and annotations carry safety. The description covers purpose, scope, and non-goals adequately. Only the absence of routing guidance against the other orientation-style siblings keeps it from being fully complete.

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

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

There is one parameter (response_format), and schema description coverage is 0%, so the description must compensate but adds nothing about output formatting. The parameter is a simple two-value enum with a default, so its meaning is largely self-evident from the schema, warranting the baseline rather than a penalty.

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 verb and resource ('Inventory supported Polar data domains') and enumerates the concrete contents (auth scope requirements, privacy boundary, recommended first calls). The closing clause 'Does not call Polar APIs or expose user data' cleanly separates it from the many siblings that actually fetch Polar data, so an agent can distinguish it without opening any schema.

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

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

The phrase 'recommended first calls' implies this is an orientation/onboarding entry point, and the non-goal clause implies it is not a data-fetching tool. However, it never states explicitly when to call this versus siblings like polar_capabilities, polar_agent_manifest, or polar_quickstart, which look like competing orientation 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description's key added value is disclosing that the returned payloads are synthetic examples rather than real data — an important behavioral fact not in the annotations. It does not mention auth requirements or that only three of many tools are covered.

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

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

One front-loaded sentence with the verb+resource first and the rationale second. No filler; the list of covered tools is the only detail and it earns its place.

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

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

There is no output schema, so the description should carry more of the return-shape burden. It says payloads exist but not whether all three are returned together, how they are keyed, or how response_format affects the output. Adequate for a simple read-only demo tool, but with clear 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 0% and the single parameter (response_format, enum markdown/json, default markdown) is never mentioned in the description. With one enum parameter carrying a default, the description should clarify output format behavior but does not compensate for the coverage gap.

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

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

States a specific verb (returns) and a specific resource (example payloads), and names the exact three sibling tools whose contracts it mirrors (polar_daily_summary, polar_wellness_context, polar_list_nightly_recharge). An agent can immediately tell this is a preview/sample tool rather than a live data fetch.

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 clause 'so agents see the contract before calling real Polar APIs' gives clear usage context: call this first to inspect shape, then call the real tools. There are no explicit exclusions or alternatives for the ~27 other siblings whose contracts are not demoed, so it stops 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.

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

Adds substantive behavior beyond the annotations: tokens are persisted locally with 0600 permissions and are never returned to the caller. That is security-relevant context the openWorldHint/idempotentHint flags do not convey. It does not cover failure modes or what happens to previously stored tokens on re-exchange, keeping it short of a 5.

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

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

Two sentences, front-loaded with the core action, followed by the storage guarantee and the user prerequisite. No filler; every clause adds information the agent needs.

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

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

With an output schema present, return values need not be explained, and the description still clarifies that no token value is surfaced. Combined with the annotations and the security/permission note, an agent has enough to invoke this correctly; only error and re-exchange behavior are unaddressed.

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

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

Schema coverage is exactly 50%: the required `code` parameter is well documented in the schema (including the full-redirect-URL form), while `response_format` is an undescribed enum. The description only restates 'authorization code' and adds no format, validation, or output-shaping detail beyond the schema, so the baseline of 3 applies.

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

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

States a precise verb+resource pair: exchange an OAuth authorization code for local tokens. This clearly distinguishes it from the sibling polar_get_auth_url (which starts the flow) and from all the polar_list_* read tools.

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

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

Explicit precondition and workflow context: the user must complete browser OAuth first, and agents must not invent codes. This tells the agent when the tool is applicable and guards against a common misuse, though it never names the sibling tool (polar_get_auth_url) that produces the code.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the auth scope requirement (profile:read), which is useful context, but says nothing about the privacy_mode escalation path or what the raw mode exposes beyond what the schema already states.

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

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

Two short sentences, front-loaded with purpose and followed by the precondition. Nothing is wasted and there is no 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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description still leaves sibling selection (polar_profile_get) and the raw-mode escalation behavior unaddressed, which matters for a tool with a privacy-sensitive parameter.

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

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

Schema coverage is only 67%, and the description contributes no parameter information at all. privacy_mode and explicit_user_intent are documented in the schema, but response_format has no description anywhere, and the description does not compensate for that gap or explain how privacy_mode interacts with the scope requirement.

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

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

States a specific verb+resource ('Read Polar user account fields') and names the upstream system (AccessLink), so the agent knows this retrieves account-level data. It does not, however, differentiate itself from the close sibling polar_profile_get, leaving a genuine ambiguity about which one to call.

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 one real usage signal, the required scope ('Requires profile:read'), which is a prerequisite rather than a when-to-use rule. It offers no guidance on when to prefer this over polar_profile_get, polar_data_inventory, or the privacy-audit tools, so selection is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the token-absence precondition, which is real behavioral context, but it omits the OAuth flow relationship (that the returned URL leads to a code exchanged via polar_exchange_code) and any auth/permission notes.

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

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

Two short sentences with the action stated first and the usage condition second. Every sentence earns its place with zero 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. However, as the entry point of a multi-step OAuth flow, the description should mention the follow-up step (exchange code) so the agent understands the sequence; that linkage 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 67% — state and scopes are documented in the schema while response_format is not. The description adds no parameter meaning at all, leaving the partial coverage gap unaddressed, so it sits at the adequate baseline.

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

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

The description states a specific verb and resource: "Generate a Polar OAuth authorization URL." This clearly identifies the action and object, so an agent can tell it apart from data-fetching siblings like polar_list_sleeps. It does not, however, name or differentiate itself from the closely related sibling polar_exchange_code.

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

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

"Use this first when no local token exists" gives an explicit trigger condition and ordering ('first'), which is genuinely useful routing guidance. It stops short of naming the alternative (polar_exchange_code) or stating when not to use it, so it is clear but not exhaustive.

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 cover read-only, idempotent, open-world, non-destructive semantics. The description adds two important operational facts beyond annotations: route data is GPS-sensitive and default privacy modes redact coordinates, plus the required auth scope.

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

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

Three short sentences, front-loaded with the core action and followed by the two most important caveats (GPS/privacy, auth). No 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?

For a read-only getter with annotations and an output schema, the description supplies the key call prerequisites and privacy behavior. It omits usage alternatives and response_format guidance, but those are lower priority given schema coverage and the presence of an output schema.

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

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

Schema description coverage is 75%, so baseline is 3. The description reinforces route_id and default privacy redaction, but adds little detail for privacy_mode, response_format, or explicit_user_intent 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?

Names a specific verb ('Load') and resource ('Polar route') scoped by route id, distinguishing it from the many list_* siblings. It does not explicitly compare against an alternative, but for a get-by-id tool the action 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?

States the required scope ('Requires routes:read') but does not say when to prefer it over related listing tools or how to obtain a route id beyond the schema. Usage is implied by 'by route id', so not absent, but alternatives and exclusions are missing.

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, idempotentHint, non-destructive and openWorld, so the safety profile is covered structurally. The description adds real value beyond that: bounded output (500-point cap), a named payload contract ('agent-safe-series/v1'), and a precision/size tradeoff between full-resolution stats and the capped series. It still omits latency, auth requirements, and empty-window 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?

Four tight sentences with the core purpose front-loaded and the routing hint for polar_daily_summary placed early. The 'Shared contract with garmin/strava/fitbit series tools' line adds cross-tool context at minimal cost, though the jargon-y contract tag is a small readability tax.

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

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

An output schema exists, so return-value explanation is unnecessary, and the read/mutation semantics are covered by annotations. However, for a 5-parameter tool with 20% schema coverage, the description leaves key inputs (resolution_seconds, reference_max_hr) unexplained and never states a when-not-to-use condition.

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 only 20% – essentially just 'date'. The description explains the 500-point ceiling implied by max_points but adds nothing about resolution_seconds, reference_max_hr (used for HR zone context), or response_format. With low coverage, the description should compensate for the undocumented parameters and does not.

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

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

States a specific resource (heart-rate series derived from Polar continuous samples) with a clear scope qualifier ('bounded', 'capped at 500 points') and distinguishes its output model (exact stats on full-resolution samples plus a downsampled series). It does not explicitly name polar_list_continuous_samples as the raw-sample alternative, so sibling differentiation is partial.

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

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

Gives an explicit routing instruction: 'Prefer polar_daily_summary first,' which tells the agent when to reach for another tool before this one. It stops short of stating when this tool is the wrong choice or what conditions require the full series over the summary.

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/idempotentHint/destructiveHint=false, so the safety profile is covered structurally. The description adds the required OAuth scope ('activity:read'), which is genuinely useful context not present in annotations. It says nothing about pagination behavior, the privacy_mode override, or the raw-mode escalation requirement.

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

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

Two short sentences with the core action front-loaded and no filler. It is efficient, though bordering on under-specified rather than concise for a 10-parameter 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?

This is a 10-parameter tool with pagination (all_pages/max_pages), feature flags, and a privacy_mode override that can require explicit_user_intent=true for raw. None of that complexity is acknowledged in the description. An output schema exists, so return values needn't be explained, but the invocation-time caveats are 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 90%, so the schema already documents the page/after/before/limit/features/privacy_mode parameters, including enum values. The description adds no parameter-level meaning beyond that, which is acceptable given the high coverage baseline.

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

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

States a specific verb+resource ('List Polar daily activity records'), which is clear on its own. However, with many similarly named siblings (polar_list_sports, polar_list_training_sessions, polar_daily_summary, polar_list_continuous_samples), the description does not distinguish what 'activity' covers versus those adjacent datasets.

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?

'Requires activity:read' is a prerequisite, not usage guidance. Nothing tells the agent when to pick this over polar_daily_summary or polar_list_sports, and no exclusions or alternatives are named.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds the non-obvious authorization requirement (calendar:read), which is real value beyond annotations, but says nothing about the privacy redaction escalation or pagination behavior that the schema only partially conveys.

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

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

Two tight sentences with the core action front-loaded and zero filler. It is efficient, though the terseness leaves room for useful detail about the 10-parameter surface.

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 10-parameter tool the description is thin, but an output schema exists, annotations carry the safety profile, and schema coverage is 90%, so most of the burden is already handled elsewhere. The notable gap is that the explicit_user_intent escalation rule tied to privacy_mode=raw is left entirely to the schema.

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

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

Schema description coverage is 90%, so the baseline is 3; the schema already documents date patterns, pagination bounds, and the privacy_mode enum. The description's only parameter-adjacent content is the date-range framing, which adds no syntax or semantics beyond what the schema provides.

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

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

States a specific verb (List), resource (Polar calendar entries), and scope (date range), which cleanly separates it from the other polar_list_* siblings that target activities, sleeps, sports, etc. It does not name an alternative or contrast against any sibling, but the resource is unique enough that an agent can place it without opening the schema.

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

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

"Requires calendar:read" is a permission prerequisite, not usage guidance. There is no statement of when to pick this tool over related list tools, no mention of how privacy_mode/explicit_user_intent interact, and no exclusions. The agent gets a precondition but no routing advice.

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 a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds the required OAuth scope and a health-adjacent caveat ("Not medical advice"), which are real behavioral context, though it does not describe pagination or volume characteristics.

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

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

Three short sentences, front-loaded with the core action and scope, followed by the permission and alternative. No filler, though the closing disclaimer is boilerplate that a stricter reading could trim.

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 10-parameter read-only list tool with an output schema, the essentials are covered: what it returns, the scope rule, the auth scope, and the safer sibling alternative. Return format and pagination semantics are handled by the schema, so little is missing, though the privacy/redaction escalation path is left entirely to parameter docs.

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 90%, so the schema already documents pagination, date bounds, privacy_mode, and explicit_user_intent. The description adds no parameter syntax, defaults, or interaction rules (e.g., the raw-privacy escalation) beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ("List continuous sample records") plus the date-range scope, and explicitly names the sibling to prefer instead (polar_heart_series). An agent can distinguish it from the many other polar_list_* tools without opening a schema.

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

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

Gives a concrete prerequisite ("Requires continuous_samples:read") and a routing rule to an alternative ("Prefer polar_heart_series for agent-safe bounded HR series"). It stops short of stating when this tool is the correct choice or any exclusions, so it is clear context rather than full when/when-not 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 cover read-only, idempotent, non-destructive, and open-world behavior. The description adds the authorization scope requirement and a disclaimer ('Not medical advice'), but does not describe pagination, rate limits, or return behavior, so it adds limited value beyond structured fields.

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

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

Three short, front-loaded sentences with no wasted words. Purpose is stated first, followed by the permission requirement and a disclaimer.

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 that an output schema exists and schema coverage is high, the description need not explain return values or parameters in detail. It covers purpose, permission, and a compliance disclaimer, which is sufficient for an agent to invoke it correctly, though mentioning pagination or privacy controls could add marginal value.

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 90%, so the baseline is 3. The description only implies date-range filtering, which is already fully documented in the schema; it adds no additional parameter 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 uses a specific verb 'List' and resource 'Nightly Recharge results' with scope 'date range', making the purpose clear. It does not explicitly differentiate from siblings like polar_list_sleeps or polar_daily_summary, but the resource is distinct 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?

Only a permission requirement is stated ('Requires nightly_recharge:read'). There is no guidance on when to use this tool versus alternatives, nor any exclusions or contextual cues for selecting it among the many polar_list_* siblings.

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=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the scope requirement (ppi_data:read), which is genuine extra value, but says nothing about pagination behavior, rate limits, or the privacy/escalation mechanics (privacy_mode=raw requires explicit_user_intent=true) that govern actual calls.

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

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

Two short sentences, zero filler, and the core capability is front-loaded before the permission constraint. Nothing in the text is redundant with the name or 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. However, for a 10-parameter tool with privacy modes and redaction-escalation semantics, the description omits anything about the raw-privacy escalation path or pagination limits, leaving the agent to discover those entirely from the schema.

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

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

Schema description coverage is 90%, so the schema already documents page, after, before, limit, features, all_pages, max_pages, privacy_mode, response_format, and explicit_user_intent in detail. The description adds no parameter-level information beyond the implicit date-range framing, so the baseline 3 for schema-driven documentation applies.

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

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

States a specific verb and resource ("List pulse-to-pulse interval samples") with a scoping qualifier ("in a date range"), which is enough to separate it from sibling list tools like polar_list_continuous_samples or polar_heart_series. It does not explicitly name or contrast those siblings, so it stops short of a 5.

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

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

The description implies when the tool is usable via the date-range scope and the "Requires ppi_data:read" prerequisite, which tells the agent whether it can be attempted at all. It offers no explicit routing advice though — nothing says when to prefer this over polar_list_continuous_samples or polar_heart_series, and no exclusions.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered structurally. The description adds the auth scope requirement, but is silent on pagination behavior, privacy_mode defaults, and the explicit_user_intent escalation the schema implies.

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, action front-loaded, then the permission requirement. 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?

For a read-only list tool with an output schema and 90% parameter coverage, what is missing (return shape) is documented elsewhere. The description is nearly complete, though the privacy/redaction surface is more involved than a single scope sentence suggests.

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 90%, so the schema carries parameter meaning (pagination, date formats, privacy modes) on its own. The description adds no parameter-level detail beyond the date-range hint, which the schema already encodes.

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

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

States a specific verb and resource ("List skin contact periods") plus a scoping constraint ("in a date range"). There is no sibling that also lists skin contacts, so differentiation is inherent rather than demonstrated.

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

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

Names the required scope (skin_contact:read), which is a genuine prerequisite, but says nothing about when to prefer this over alternatives or when it should not be used. Usage is only implied by the tool name and scope.

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, idempotentHint and non-destructive, so the safety profile is covered. The description still contributes the OAuth scope requirement (sleep:read) and the non-medical-advice caveat, which are behavioral facts not present in the structured fields. It stops short of describing pagination or privacy-mode behavior, but the schema covers those.

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, purpose front-loaded, then auth requirement, then safety caveat. Nothing is redundant and there is no 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?

With an output schema present and annotations covering the read-only safety profile, the description needs only to establish purpose and prerequisites, which it does. The one gap is that neither the description nor an explicit sentence points the agent at pagination or privacy-mode conventions, though both are documented in the schema.

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

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

Schema description coverage is 90% across 10 parameters, so the schema itself documents page, after/before, limit, all_pages, privacy_mode and explicit_user_intent thoroughly. The description adds no parameter-level detail beyond what the schema already supplies, making the baseline 3 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?

States a specific verb (List) and resource (Polar sleep records) with the scoping constraint (date range), which is enough to separate it from most siblings like polar_list_activity or polar_list_sports. It does not, however, explicitly distinguish itself from the closest neighbors such as polar_list_nightly_recharge or polar_list_sleep_wake_vectors, which an agent must infer from the noun alone.

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

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

"Requires sleep:read" gives a real prerequisite, and the medical disclaimer signals domain caution, so usage is partially implied. There is no guidance on when to choose this over the other sleep-adjacent listing tools, nor any exclusion or alternative named.

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 cover readOnly, idempotent, openWorld, and destructive=false, so the safety profile is clear. The description adds 'Requires sleep:read' (an auth requirement) and 'Not medical advice' (a disclaimer), which are useful beyond the annotations, but it omits pagination and privacy-mode behavior. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Three short sentences, front-loaded with the action and resource. Each sentence earns its place: purpose, permission requirement, and a health-data disclaimer. There is no wasted text.

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

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

For a 10-parameter read tool with an output schema and rich annotations, the description supplies only purpose, auth, and a disclaimer. It omits when to choose this over sibling list tools and does not mention the privacy_mode/explicit_user_intent escalation, leaving gaps for the schema to carry alone. It is minimum viable but not complete.

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

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

Schema description coverage is 90%, so the schema already documents all ten parameters, including the two enums and the privacy_mode/explicit_user_intent relationship. The description only implies date-range filtering and adds no parameter-level meaning beyond what the schema provides. Baseline 3 is correct.

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

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

States a specific verb 'List' and resource 'sleep/wake vector records' with scope 'in a date range'. It does not distinguish itself from sibling list tools such as polar_list_sleeps or polar_list_nightly_recharge, so 4 rather than 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?

No when-to-use, when-not-to-use, or alternative-tool guidance is provided. 'Requires sleep:read' is a prerequisite rather than usage direction, and the date range is implicit from the purpose statement. The agent is not told when this tool is the right choice.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the sports:read scope requirement, which is useful, but says nothing about pagination behavior, the privacy_mode default, or the fact that explicit_user_intent must be true for raw/include_gps escalation.

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 clauses, front-loaded with the action and followed by the permission requirement. No padding, though the extreme brevity leaves obvious gaps unaddressed.

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 10-parameter tool with privacy-mode overrides, pagination flags, and an escalation gate (explicit_user_intent), yet the description is a single sentence. Even accounting for the output schema and 90% schema coverage, the description omits the privacy/escalation semantics that materially affect 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?

Schema description coverage is 90%, so the schema already documents page, after, before, limit, features, all_pages, max_pages, privacy_mode, response_format and explicit_user_intent. The description adds no syntax, format, or interaction detail beyond the schema, so the baseline 3 applies.

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

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

"Load Polar sport profile catalog" names a verb and a resource, but the sibling set contains both polar_list_sports and polar_list_sport_profiles, and the description gives no basis for distinguishing "catalog" from "sports" or "profiles." An agent cannot reliably route between these three tools from the text alone.

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

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

"Requires sports:read" states a scope prerequisite but no when-to-use condition, no exclusions, and no mention of the near-identical sibling tools. There is no guidance on when this catalog is preferable to polar_list_sports or polar_list_sport_profiles.

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=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the required scope (sports:read), which is genuinely useful context. It says nothing about the pagination model (page/limit/all_pages) or the privacy_mode/explicit_user_intent escalation behavior, which are the non-obvious behaviors of this 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?

Two short sentences, front-loaded with the action and immediately followed by the prerequisite. There is no filler, hedging, 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?

An output schema exists, so return values need not be explained, and the description covers the core purpose and auth. Still, with 10 parameters including privacy overrides and an agent-escalation flag, the description omits any mention of the privacy modes or explicit intent requirement, leaving non-obvious operational context only in the schema.

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

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

Schema description coverage is 90%, so the schema itself documents all 10 parameters well, making 3 the baseline. The description contributes no additional parameter meaning, formatting hints, or interaction rules (e.g. that all_pages works with max_pages) beyond 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?

States a specific verb and resource ('List the user's Polar sport profiles'), which is concrete and unambiguous on its own. However, it does nothing to distinguish itself from the closely named siblings polar_list_sports and polar_list_sport_profile_catalog, so an agent must still guess which of the three it wants.

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 only guidance is an authorization prerequisite ('Requires sports:read'), which tells the agent about scope but not when this tool is the right choice versus polar_list_sports or polar_list_sport_profile_catalog. No when-to-use condition or exclusion is 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one useful, non-annotation fact: the required sports:read scope. It says nothing about pagination behavior, privacy_mode/explicit_user_intent escalation, or response shape.

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, purpose front-loaded, no filler. Nothing in the text is redundant with the title or restated unnecessarily.

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

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

An output schema exists, so return values need not be explained, and annotations plus a rich 10-parameter schema carry most of the burden. The gap is that the unusual privacy/escalation parameters (privacy_mode=raw requiring explicit_user_intent) are only covered in the schema, not surfaced in the description.

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 90%, so the schema already documents page, limit, before/after, privacy_mode and the rest. The description contributes no parameter-level detail beyond the auth scope, making the baseline 3 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?

States a specific verb and resource ('List sports available in the Polar ecosystem'), so the agent knows the returned entity type. However, it does not distinguish itself from near siblings such as polar_list_sport_profiles or polar_list_sport_profile_catalog, whose names suggest overlapping content.

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 only guidance is the auth prerequisite 'Requires sports:read', which is a precondition rather than a when-to-use rule. Usage is implied (call it when you need the catalog of sports), but there is no exclusion or alternative-tool routing toward sport profiles.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the auth-scope requirement, which is genuine value beyond the annotations, but says nothing about pagination, privacy levels, or the raw/redaction escalation path that the schema exposes.

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

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

Two short sentences, with the purpose front-loaded and the precondition second. No filler, though it is arguably too terse rather than too long — the efficient structure is the main strength.

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, return values need not be explained, and annotations cover safety. However, for a 10-parameter tool with privacy-mode overrides and an explicit_user_intent escalation gate, the description omits that these behaviors exist, leaving the agent to discover them only in the schema.

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

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

Schema description coverage is 90%, so the schema already documents page, after, before, limit, all_pages, max_pages, privacy_mode, response_format and explicit_user_intent in detail. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

Specific verb+resource: 'List user subscriptions and entitlements' clearly states the operation and the data returned. It does not differentiate itself from the many sibling polar_list_* tools (e.g. polar_list_user_devices, polar_list_sports), but the resource is distinct enough that an agent can match it to a subscription-related request.

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 adds one actionable precondition ('Requires user_subscription:read'), which tells the agent it may need elevated scope. It gives no guidance on when to prefer this tool over other listing tools or on filtering behavior, so usage context remains implied.

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=true, idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds a genuinely useful auth requirement ('Requires temperature_measurement:read'), but says nothing about pagination, privacy_mode behavior, or redaction escalation that the tool supports.

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

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

Two short sentences with zero waste; the scope (date range) and the permission requirement are both front-loaded 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?

With an output schema present and 90% schema coverage, the description need not explain return values or most parameters. It covers the core purpose and the required scope, though it omits any hint of the privacy_mode/raw escalation flow that the tool exposes.

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 90%, so the schema already documents all ten parameters (page, after, before, limit, features, privacy_mode, etc.). The description only echoes the date-range concept, adding no syntax or format detail beyond what the schema provides. 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?

States a specific verb ('List') and resource ('temperature measurements') plus a scoping constraint (date range), so the agent can tell what it returns. However, it does not differentiate from the many sibling polar_list_* tools (e.g. activity, sleeps, sports) beyond the resource name itself.

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?

'in a date range' implies when it applies, and 'Requires temperature_measurement:read' gives a prerequisite. But there is no explicit when-to-use vs alternatives guidance or exclusion criteria among the crowded polar_list_* family.

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, idempotentHint, non-destructive, and openWorld, so the safety profile is covered. The description adds the required auth scope (tests:read), which is genuinely useful context beyond the annotations, but says nothing about pagination, privacy redaction, or the raw-mode escalation requirement.

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

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

Two sentences, zero filler, with the resource and scope front-loaded before the permission note. Every clause earns its place.

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

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

With an output schema, 90% schema coverage, and full annotations, the description is minimally sufficient. But for a 10-parameter tool offering privacy_mode=raw and include_gps escalation, the absence of any note about the explicit_user_intent gate or the multi-page fetching behavior leaves context the agent must reconstruct from the schema.

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

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

Schema description coverage is 90%, so the schema already carries the parameter burden (page/limit/all_pages/max_pages/privacy_mode/explicit_user_intent are all described). The description's 'date range' phrasing hints at after/before but adds no format or boundary semantics beyond what the schema states.

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

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

States a specific verb (List) and a precisely scoped resource (Polar fitness/orthostatic/running test results) bounded to a date range. It is clearly distinguishable from the other polar_list_* siblings, though it never names an alternative or contrast explicitly.

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

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

The only guidance is the prerequisite 'Requires tests:read', which is useful but not usage guidance in the when-to-use sense. It never says when this tool should be chosen over e.g. polar_list_activity or polar_daily_summary, leaving the agent to infer from the resource name.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered without the description. The description does add one useful non-annotation fact – the required training_sessions:read scope – but says nothing about pagination behavior, privacy_mode redaction effects, or what the raw escalation entails.

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

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

Two short sentences with zero padding; the scope constraint leads and the auth requirement follows. Nothing is repeated from 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?

An output schema exists, so return values need not be described, and the schema is rich at 90% coverage. However, for a 10-parameter tool with a privacy escalation flag and multi-page fetching, the description leaves the agent without any narrative on the raw/explicit_user_intent escalation flow or pagination semantics.

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 90%, so the schema already documents page, after, before, limit, privacy_mode, and the rest in detail. The description adds no parameter-level meaning (e.g. how privacy_mode interacts with explicit_user_intent or all_pages), so the baseline 3 applies.

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

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

States a specific verb ('List') plus resource ('Polar training sessions') and a scoping constraint ('in a date range'), which distinguishes it from the many other polar_list_* siblings such as polar_list_activity and polar_list_tests. It stops short of explicitly naming a sibling it differs from or clarifying the boundary against those adjacent list tools.

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

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

The only guidance is the prerequisite 'Requires training_sessions:read.', which is an auth note rather than a when-to-use rule. There is no indication of when to prefer this over polar_list_activity, polar_list_tests, or polar_list_training_targets, and no exclusions or pagination advice.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered without the description. The description does add one non-obvious behavioral fact, the training_targets:read scope requirement, which is genuine added value, but it omits pagination behavior and how favorites are ordered or filtered.

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, purpose front-loaded, with the prerequisite stated second. No filler, no repetition of the title, and nothing that could be cut without losing information.

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

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

An output schema exists so return values need not be explained, and annotations fully cover the safety profile; the auth scope requirement is a useful addition. The only meaningful gap is the lack of differentiation from the sibling polar_list_training_targets, which matters for a tool whose name hinges on 'favorites'.

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 90% across 10 parameters, so the schema already documents page, limit, before, after, all_pages, privacy_mode, and explicit_user_intent in detail. The description adds nothing about parameter semantics, and the baseline of 3 applies when the schema does the heavy lifting.

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

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

Names a specific verb and resource: lists the user's training target favorites. The purpose is unambiguous on its own, but it does not distinguish itself from the sibling polar_list_training_targets, so an agent must infer the favorites-vs-all distinction from the name alone.

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

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

The description implies when the tool is applicable (when you want favorites) and states the required scope, but gives no explicit when-to-use guidance, exclusions, or naming of the alternative polar_list_training_targets for the full list.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the auth scope requirement, which is useful, but says nothing about pagination behavior across the 10 params or what the read returns.

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

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

Two short sentences, zero filler, with the core action front-loaded before the prerequisite. Nothing in it is redundant with structured fields.

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 rich annotations, a 90%-covered schema, and an output schema present, the description only needs to anchor purpose and prerequisites, which it does. It falls short only on sibling differentiation and pagination context, which are minor given the structured coverage.

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 90%, so the schema already documents page, after, before, limit, features, privacy_mode, and the rest. The description adds no parameter-level meaning (e.g. that before is exclusive or how all_pages/max_pages interact), so baseline 3 applies.

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

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

States a specific verb ('List'), resource ('calendar training targets'), and scope ('in a date range'). It is clear on its own, though it does not distinguish itself from the nearby sibling polar_list_training_target_favorites, which an agent could easily confuse it with.

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

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

Gives a hard prerequisite ('Requires training_targets:read'), which is genuinely actionable. However, it offers no when-to-use guidance versus alternatives such as polar_list_training_target_favorites or polar_list_training_sessions, so selection still requires 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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds the concrete auth scope requirement ('Requires devices:read'), which is not derivable from the annotations. It doesn't mention pagination semantics or the privacy_mode escalation behavior, keeping it below 5.

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

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

Two short sentences, front-loaded with the purpose and followed by the auth requirement. Every sentence earns its place with zero 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?

For a read-only list tool with a rich 10-parameter schema, full annotations, and an output schema, the description is sufficient at minimum. However, it omits the pagination model (page/limit/all_pages) and the privacy_mode/explicit_user_intent escalation contract, which are non-trivial behaviors an agent should grasp before calling.

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 90%, so the schema itself already documents page, after, before, limit, features, all_pages, max_pages, privacy_mode, and explicit_user_intent well. The description adds no additional parameter meaning, so baseline 3 applies.

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

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

States a specific verb ('List') and resource ('devices registered to the Polar user'), which cleanly distinguishes it from the many sibling list_* tools (activity, sleep, sports, etc.). No ambiguity about what is returned at a high level.

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 usage via the scope line ('devices registered to the Polar user') and the auth requirement, but it never states when to prefer this over siblings or any preconditions beyond the scope. Adequate but with clear gaps for an agent navigating 35+ 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?

"Read-only" merely restates readOnlyHint=true, earning no credit. The description does add useful context beyond annotations by disclosing what is returned (questionnaire, shared profile, missing critical fields, cross-connector hint), but it says nothing about caching, rate limits, or how the hint is derived.

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

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

Two sentences, front-loaded with the read-only constraint and the return payload before the usage trigger. The long field enumeration in the second sentence is dense but functional; nothing is wasted.

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

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

With no output schema, the description carries the burden of describing returns and does so by enumerating the payload. Both parameters are optional and the safety profile is covered by annotations, so only the response_format semantics remain unexplained.

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 50%: locale is documented, response_format is not. The description mentions the locale options ("en or pt-BR") but adds nothing about response_format or the markdown/json output difference, so it only marginally compensates for the schema gap.

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

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

States a specific verb (Return) plus the exact resource (the 11-question Delx Wellness onboarding flow) and enumerates the payload contents: shared profile, missing critical fields, cross-connector hint. This is clearly distinguishable from siblings like polar_profile_get or polar_wellness_context.

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

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

"Use this when the user starts a fresh wellness session" gives a concrete triggering condition and lists the fields it is meant to populate (preferred_name, goals, devices, safety, etc.). It does not name an alternative or state when not to use it, so it falls 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.

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

Annotations already declare this a safe read-only, idempotent, non-destructive, closed-world operation. The description adds genuine value beyond that by committing to a redaction guarantee ('without revealing secret values') and enumerating the inspected surfaces, which matters for a security-sensitive audit 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?

A single front-loaded sentence leads with the return verb and the security caveat, with no filler. Every clause carries scope information.

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

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

An output schema exists, so return-value explanation is not required, and rich annotations cover the safety profile. What remains thin is routing guidance against overlapping sibling tools, otherwise the definition is complete for a read-only audit call.

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

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

Schema description coverage is 0%, so the single response_format parameter (markdown/json, default markdown) is undocumented in both the schema and the description. The description never mentions output format options, so it fails to compensate for the coverage gap even though the enum is fairly self-explanatory.

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

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

The description gives a specific verb ('Return') and an enumerated resource ('local privacy, cache, token-path and env-presence posture'), so an agent knows exactly what surface it inspects. It does not, however, differentiate itself from overlapping siblings such as polar_cache_status or polar_data_inventory, which likely return related posture data.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives like polar_cache_status (cache focus) or polar_connection_status. Usage is only vaguely implied by the audit framing, leaving the agent to guess how this differs from the neighboring status 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?

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered; the description adds genuinely new context by bounding the data contents (only onboarding-typed data, never OAuth tokens, API keys, or biomarkers). It does not say whether the profile can be empty or how sharing with other connectors is governed, so it stops short of a 5.

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

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

Three short, front-loaded sentences with no filler; the identity of the resource comes first, followed by the safety scope. Every sentence carries information.

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

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

With no output schema, the description should characterize the return; it partially does by scoping what the profile does and does not store. It omits the actual profile fields returned and the response_format behavior, which are the remaining gaps for a zero-required-parameter read tool.

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

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

Schema description coverage is 0% and the description never mentions the single response_format parameter (markdown/json, default markdown). The enum values are largely self-explanatory, so this is a minor gap rather than a severe one, but the description does not compensate for the uncovered 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?

States a specific verb (Read) and a specific resource (the canonical Delx Wellness profile), and identifies the profile's scope (shared across wellness MCP connectors). This is clearly separable from the sibling polar_profile_update, which writes the same resource.

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

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

Usage is implied ('Read the canonical... profile') but there is no explicit when-to-use guidance, no statement of prerequisites, and no routing to the obvious alternative polar_profile_update for write scenarios. Adequate but leaves the choice between read and update 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 readOnly=false, idempotentHint=false and destructiveHint=false. The description adds meaningful behavior beyond that: it refuses to write without explicit user intent and rejects secret-like fields (oauth, token, api_key, password, etc.). Those are real operational constraints the annotations don't convey. It stops short of describing auth requirements or return 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?

Three sentences, each carrying distinct information (what it does, the intent gate, the field rejection) with the action front-loaded. No filler or repetition.

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 mutation tool with annotations covering the safety profile and a documented patch schema, the remaining gaps are minor. An agent knows what it writes, the precondition, and the disallowed content. The absence of an output schema means no return-value explanation is owed.

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 67%, so the schema documents patch and explicit_user_intent. The description reinforces the explicit_user_intent gate and adds the secret-field rejection rule, which meaningfully constrains what the free-form patch object may contain. This goes beyond the schema's property-level documentation, though it doesn't detail patch merge/precedence semantics.

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

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

States a specific verb and resource: 'Persist a partial patch to the canonical Delx Wellness profile.' The 'partial patch' framing usefully distinguishes it from a full-document write. It does not explicitly name the read counterpart (polar_profile_get), but the name pairing makes the distinction self-evident.

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

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

Gives a clear precondition — 'Requires explicit_user_intent=true after the user confirms they want to save' — that tells the agent exactly when a write is permissible. No explicit 'when not to use' against a sibling alternative, but the confirmation gate is strong, actionable context.

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/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it adapts to current state (env vars, token presence) and produces a 3-step walkthrough aimed at the human user rather than returning raw data.

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

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

Two tight sentences, front-loaded with the deliverable and then the trigger condition. No filler, every clause carries information.

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

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

For a read-only, zero-required-parameter walkthrough tool with no output schema, the description covers purpose, audience, adaptive behavior, and invocation timing. The only omission is any hint that output can be markdown or json, which the schema supplies.

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

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

Schema description coverage is 0% and the only parameter (response_format, enum markdown/json with a markdown default) is never mentioned in the description. The name is self-explanatory, but by the stated rule the description should compensate for the zero coverage and does not.

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

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

States a specific deliverable: a personalized 3-step setup walkthrough for the human user, with an adaptive aspect. This is clearly distinct from data-listing siblings, though it never explicitly names the closest alternatives (polar_onboarding, polar_connection_status) to sharpen 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?

Gives explicit when-to-use guidance: 'Call this first when the user asks how do I connect Polar?'. There is no when-not guidance or named alternative, but the trigger condition is clear and actionable.

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 carry the destruction profile (destructiveHint=true, readOnlyHint=false, idempotentHint=false), and the description adds useful specifics beyond them: what exactly is destroyed (the local token file), the scope limit (remote grant is not necessarily revoked), and the intent gate that prevents autonomous agent invocation.

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

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

Two tight sentences with no filler; the destructive action and its scope are front-loaded, followed immediately by the usage restriction and gate.

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

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

An output schema exists so return values need not be described, and the annotations cover safety. The remaining gap is the ambiguous 'revoke the remote grant from Polar if needed' clause, which leaves unclear whether this tool reaches the remote server.

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 50%, and the description meaningfully explains the gating semantics of explicit_user_intent beyond the schema text. But response_format is documented in neither schema nor description, so coverage is only partially compensated.

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: 'Delete the local Polar token file.' It is unambiguous and clearly distinct from siblings such as polar_get_auth_url and polar_exchange_code, which handle the opposite direction of the auth lifecycle.

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 an explicit when-to-use condition ('only when the user explicitly wants to disconnect this MCP') and a hard gate ('explicit_user_intent: true'). However, 'revoke the remote grant from Polar if needed' is ambiguous about whether this tool performs that revoke or the caller must do it separately, and no alternative sibling is named.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the 'non-medical' disclaimer and lists the aggregation contents, which is useful context, but says nothing about latency, rate limits, or how the scorecard is computed.

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

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

A single front-loaded sentence with no filler; the scope and content list are delivered immediately and the read-only/non-medical caveat is appended economically.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The content list plus the non-medical caveat are adequate for calling the tool, though routing relative to polar_daily_summary is absent.

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 75%: days, timezone and compare_days are documented in the schema, while response_format has an enum but no description. The description adds no parameter-level meaning, so the baseline of 3 for near-complete schema coverage applies.

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

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

States a specific verb and resource ('Build a weekly Polar scorecard') and enumerates the content it aggregates (sleep, activity, Nightly Recharge, training load, bottlenecks, actions). It does not explicitly differentiate itself from the closely related sibling polar_daily_summary, so it falls short of a 5.

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

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

There is no when-to-use guidance, no condition for choosing this over polar_daily_summary or polar_wellness_context, and no stated prerequisites. The only hint is the implicit 'weekly' scope in the name and description.

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=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds that output is normalized into a 'wellness_context shape', which is useful context, but says nothing about how the optional inputs (soreness, injury_flags, notes) influence results or what happens when no Polar data exists for the window.

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