Wincher MCP by usefulapi

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

Adds substantial behavior beyond the annotations: each keyword permanently consumes one quota slot, the action cannot be reversed ('this tool cannot remove keywords again'), invalid or already-tracked keywords are silently ignored rather than erroring, and an unknown group name may silently create a new group. These side effects matter far more than the destructiveHint/idempotentHint flags already present.

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

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

A single dense paragraph, front-loaded with the operation class and limits, followed by quota, irreversibility, and edge-case semantics in descending order of importance. It is long but nearly every clause carries information; the trailing 'POST /websites/{website_id}/keywords/bulk' is the only borderline 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 mutation tool with no output schema, the description covers quota cost, irreversibility, duplicate handling, and group side effects. The remaining gap is what the call reports back (e.g., which keywords were actually created vs ignored), which matters precisely because invalid entries are silently dropped.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: preferred_url is glossed as 'the landing page expected to rank', groups are clarified as NAMES (may be empty) whose unknown values create new groups, and the 50-keyword/one-slot economics is spelled out.

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?

Opens with a specific verb+resource+scope: 'WRITE: start tracking up to 50 new keywords on ONE website.' That distinguishes it immediately from read siblings like wincher_list_keywords and wincher_get_keyword, and the 'WRITE' marker signals the operation class up front.

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?

Explains the context for use (begin tracking, consumes quota, cannot be undone) and routes to wincher_get_account for quota and wincher_list_groups for valid group names. It stops short of an explicit 'do not use this to re-track or update existing keywords' exclusion, so it is clear context without full 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write/no-op profile is covered. The description adds value beyond that: the note is visible to everyone with website access, it consumes no keyword quota, and omitting keyword_ids silently broadens scope to the whole website. Return payload is not described, but the safety and side-effect picture is good.

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

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

Front-loads the WRITE marker and the core purpose, then appends the scoping rule, the visibility/quota caveats, and the endpoint — every clause carries information. The single long, semicolon-chained sentence is dense but not padded.

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

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

With no output schema, an agent might still want to know whether the created annotation's id is returned, but the description covers the operation's scope, permissions implications, and cost, which is what matters for correct invocation. Adequate for a 4-parameter create 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 100%, so 3 is the baseline. The description goes past the schema by explaining the consequence of omitting keyword_ids (global note) and by framing description/date as the note text and display date, adding semantic weight rather than restating field docs.

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?

Opens with an explicit verb ('WRITE: add'), names the resource (a user annotation), and describes what it is concretely ('a note shown on the ranking graphs, e.g. Launched new landing page'). The scope (date, optional keyword linkage, global otherwise) makes it trivially distinguishable from the read-side sibling wincher_list_annotations.

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 clear selection context: supply keyword_ids to tie the note to keywords, omit them for a global website note, and states it consumes no keyword quota (a real usage consideration for a quota-limited tool). It does not explicitly name alternatives or state when not to use it, 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?

Annotations already declare the write/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description goes beyond them by disclosing the quota behavior ('Uses no keyword quota') and the optional inclusion semantics, though it says nothing about duplicate-name handling or returned identifiers.

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

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

Front-loaded with 'WRITE:' and compact at two sentences, with the quota constraint surfaced early. The trailing POST path is mildly redundant given the structured schema but is not wasteful.

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

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

With no output schema, the description omits what a created group returns (e.g., its id), which an agent may want. Otherwise it covers the required inputs, optional content, and side effects well enough to invoke the tool correctly.

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

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

Schema coverage is 100%, so name/website_id/keyword_ids are fully documented in the schema (including 'default none' and ranges). The description adds only a cross-tool pointer to wincher_list_keywords as the id source, which is helpful but marginal over the schema 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 and resource ('create a keyword group') plus its scope ('on a website') and optional content ('existing keywords'). This clearly separates it from sibling writers like wincher_add_keywords and from the read-side wincher_list_groups.

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 clear context: it is a WRITE operation, keyword ids should come from wincher_list_keywords, and it 'Uses no keyword quota' — a meaningful selection cue versus quota-consuming alternatives. It stops short of explicitly naming the alternative tool or stating when-not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the read-only safety profile is covered structurally. The description adds real value beyond that by disclosing the exact composition of the returned payload (plan limits plus current usage counters), which no annotation conveys. It stops short of mentioning auth scopes or rate limits, so a 4 rather than 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 plus an endpoint marker, front-loaded with the resource identity before the usage instruction. Every clause carries information an agent needs; nothing is padded or restated from the title.

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

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

There is no output schema, so the description must characterize the return value — and it does, enumerating every field group an agent would consume. Combined with the stated call-sequencing advice, nothing needed to invoke this zero-parameter tool correctly is missing.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. The description correctly adds no parameter discussion, and 'behind the token' implies credentials are supplied out-of-band rather than via input.

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 resource (the Wincher account behind the token) and enumerates exactly what it carries: id, timezone, plan limits with current usage across websites, users, keywords, lookups, map-tracking credits and history days. That is clearly distinguishable from siblings like wincher_get_user and wincher_get_website, which cover narrower entities.

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

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

Explicitly states the operational context: 'Check keyword usage here before adding keywords,' which routes the agent to this tool ahead of wincher_add_keywords. The condition that selects this tool is stated rather than 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context about what is returned (keyword ids plus optional ranking summary) and signals that ranking is optional, but says nothing about permissions, cost tradeoffs, or error behavior.

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

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

Two compact sentences with the return content front-loaded, followed by the endpoint route. No filler, though the REST path is largely redundant for an agent that already has the tool binding.

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 single-entity fetch with no output schema, the description conveys what the response contains (keyword ids, optional ranking summary) and hints at the period semantics. Combined with full schema coverage and covering annotations, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so all seven parameters are already documented, including the include_ranking performance caveat. The description only echoes the optional-ranking concept and adds no syntax or format detail beyond the schema, 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?

The description states a specific resource ('One keyword group') and enumerates its payload ('keyword ids and (optionally) ranking summary for the period'), clearly distinguishing it from the plural sibling wincher_list_groups. It does not name that sibling explicitly, but the singular scope is unambiguous.

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

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

Usage is only implied: 'One keyword group' suggests fetching a single known group, and the required group_id carries a hint ('from wincher_list_groups'). There is no explicit statement of when to prefer this over wincher_list_groups or feedback on the entity-level lookup vs bulk retrieval.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context about what data is returned and that ranking is included by default, but says nothing about rate limits, auth, or pagination.

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 payload description before the endpoint path. The GET path is somewhat redundant for an agent but is compact and does no harm.

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 the return, and it does so by enumerating the fields. It's largely sufficient for a read-only lookup; only edge details like pagination or empty-result behavior 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 100%, so all five parameters are documented in the schema, including the 'false is faster' hint on include_ranking and the period semantics of start/end. The description reinforces the default-ranking behavior for the period but adds no syntax or format detail beyond the schema, 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?

The description names a specific resource (one tracked keyword) and enumerates what comes back — groups, volume, CPC, difficulty, ranking — which differentiates it from siblings like wincher_list_keywords and wincher_get_keyword_ranking_history. It stops short of explicitly naming those alternatives, but the single-keyword scope is unmistakable.

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

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

Usage is only implied: 'One tracked keyword' suggests this is the single-item lookup versus wincher_list_keywords for many, but no when-to-use, prerequisites, or alternative routing is stated. It also doesn't note the parent id dependencies (website_id from wincher_list_websites) that live only in the schema.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the split-by-page/competitor behavior and the traffic-vs-position metric choice, but says nothing about granularity of the series, defaults applied to the time window, or result size.

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 capability front-loaded ahead of the endpoint path. The trailing REST path is largely redundant metadata, which costs it the top score.

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 explaining the return shape; 'as time series' and the optional per-page/per-competitor split give a rough picture, but the series granularity and default time range are unspecified. Adequate but with clear gaps for a data-retrieval 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 100%, so all six parameters are already documented in the schema; baseline is 3. The description only echoes metric ('estimated traffic') and group_by ('split per ranking page or per competitor') at roughly the same level of detail as the schema, adding almost nothing new.

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+scope: historical position or estimated traffic as a time series for ONE keyword, plus the exact REST path. The word 'ONE' implicitly separates it from the sibling wincher_get_ranking_history_bulk, but the contrast is never made explicit, so an agent must infer the routing.

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 'ONE keyword' phrasing hints at when to prefer this over the bulk variant, and the group_by option hints at drill-down use. However there is no explicit when-to-use/when-not statement or named alternative, so usage is only 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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral fact beyond that – the result cap of 30 stored SERP snapshots – but says nothing about ordering, pagination, or auth, keeping it at a moderate level of added value.

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 carries the payload and the trailing REST path is compact. The path is mild API-doc cruft that adds little for an agent, but nothing is padded or repeated.

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

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

With no output schema, the description usefully enumerates the return fields (date, search volume, SERP features, position, URL, domain, traffic) and the 30-record cap, which is enough for an agent to know what comes back. Usage context versus sibling tools is the remaining gap.

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

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

Schema description coverage is 100% and both parameters document their origin (wincher_list_keywords / wincher_list_websites). The description adds nothing about parameter meaning beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('search result pages Wincher stored for a keyword') plus the scope cap (up to 30) and the exact fields returned. This content inherently separates it from the ranking-history siblings, but no sibling is named, so the differentiation is implicit rather than explicit.

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 and no routing against alternatives like wincher_get_keyword_ranking_history or wincher_get_keyword. An agent must infer the selection criteria entirely from the returned-field list; no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds meaningful context beyond that: it explains that the tool is a read despite using POST, because keyword ids go in the body, and notes one time series per keyword.

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 tightly written sentences: purpose and batch scope are front-loaded, followed by a just-in-time clarification of the POST/read distinction. 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?

With full schema coverage and read-only annotations, the description covers enough for correct invocation: it explains the POST method, the batch limit, and the high-level return shape. It could mention the single-keyword alternative, but the core is complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description repeats the 50-keyword cap but adds no syntax or format details beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific resource (historical positions / ranking history) and a precise batch scope ('up to 50 keywords at once', 'one time series per keyword'), which clearly distinguishes it from the single-keyword sibling even without naming it. The endpoint and read nature are explicit.

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

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

Provides clear context for bulk retrieval of multiple keywords, implying use when several keywords are needed. However, it does not explicitly name or contrast with wincher_get_keyword_ranking_history for a single keyword, and offers 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?

With readOnlyHint/destructiveHint/openWorldHint already declaring the safety profile, the description still adds real value: it states the result is scoped strictly to the token's own user (no lookup of arbitrary users) and lists the concrete fields returned, which matters because there is no output schema. It stops short of describing error cases or auth failure behavior.

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

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

A single front-loaded sentence plus the endpoint reference; every clause earns its place by naming a returned field. The trailing 'GET /user' is slightly redundant but harmless.

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 no-parameter, read-only getter with no output schema, the field enumeration (id, role, state, project access, profile) is the key piece of needed information and it is present. Minor gap: 'state' and 'project access' are not explained, so the agent cannot fully interpret them.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies no input is required beyond the token.

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 the specific resource (the Wincher user tied to the calling token) and enumerates the fields returned, so an agent knows exactly what it gets. It does not, however, differentiate this from the sibling wincher_get_account, which an agent would plausibly confuse it with.

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

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

There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives such as wincher_get_account among the 21 siblings. The phrase 'the token belongs to' hints at the identity/context use case, but nothing routes the agent between this and similar get_* tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is known. The description adds a useful inventory of the returned payload (settings, competitors, brand keywords, counts, ranking summary), which is valuable given there is no output schema, but it discloses no behavioral traits like cost, auth, or rate limits.

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

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

Two compact fragments with no filler; the payload contents and the period qualification are front-loaded. It is efficient, though the trailing 'GET /websites/{website_id}' restates the resource rather than adding new 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 fetch with fully documented parameters, the description covers the returned fields (partially compensating for the missing output schema). What is thin is usage context rather than invocation detail, so it is largely complete for correct 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 100%, with each of the six parameters documented in the schema (start/end period, segment_id, include_ranking, include_serp_features). The description adds no syntax, default, or interaction detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('tracked website') and enumerates what is returned: settings, competitors, brand keywords, counts, and a period ranking summary. The singular 'one tracked website' implicitly distinguishes it from wincher_list_websites, though it never names the sibling.

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

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

Usage is only implied: fetch details for a single website. There is no explicit when-to-use phrasing, no exclusions, and no routing to alternatives such as wincher_list_websites for discovery or the keyword/history tools. The reliance on website_id conveys intent but 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds semantic context about what an annotation is and its three subtypes, but discloses no auth, rate-limit, pagination, or result-size behavior beyond that.

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 resource and scope. The trailing REST endpoint is somewhat redundant given the tool name and schema, but it is short and does not bloat the definition.

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

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

For a read-only list tool with full parameter descriptions and annotations covering the safety profile, the description supplies the core scope and return entity. It omits output shape and pagination details, but no output schema exists, so that is a minor gap rather than a blocking one.

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

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

Schema coverage is 100%, so start, end, and website_id are already documented. The description only adds that the period is optional and bounded by start/end, which is already evident from the schema, so baseline 3 is appropriate.

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

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

The description names the resource (annotations), the parent resource (a website), the annotation subtypes, and an optional filter, so an agent can tell it retrieves annotation data rather than creating it. It never states an explicit retrieval verb or differentiates itself from wincher_create_annotation, 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?

Mentions that the period is optional, which gives some implied context for filtering, but gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives like wincher_create_annotation. Usage is inferable from the name and description 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the period-scoping behavior and the underlying endpoint, but says nothing about pagination, result caps, or how many keywords are returned, which matters for a 'for each tracked keyword' fan-out.

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 scoping behavior front-loaded. The raw endpoint path is the only dubiously useful content, but the description is otherwise free of padding.

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

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

With no output schema, the description should carry more of the return-value burden. It says positions are returned per keyword for the site and each competitor, which is a reasonable start, but omits pagination, ordering, and how untracked or newly added competitors appear.

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

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

Schema description coverage is 100%, so all four parameters (website_id, segment_id, start, end) are already documented with types and cross-references. The description's 'in the period' loosely ties to start/end but adds no format or constraint detail beyond the schema's baseline 3.

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 resource and scope: for each tracked keyword, the position of the user's site and each competitor over a period. It is clearly distinct from a plain keyword list, though it never names the verb (list/retrieve) or explicitly contrasts with wincher_list_competitor_ranking_summaries, which covers similar territory.

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 choose this over siblings such as wincher_list_competitor_ranking_summaries, wincher_get_keyword_ranking_history, or wincher_get_ranking_history_bulk. The period phrasing implies a time-series query, but nothing tells the agent which of these four closely related tools to pick.

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 and destructiveHint=false, so the safety profile is covered. The description adds the returned metric set and the intent, but the REST endpoint path (GET /websites/...) merely restates the read-only nature already implied by annotations, and it says nothing about pagination, rate limits, or response size beyond what the schema's include_serp_features note already covers.

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 resource and its metric payload before the endpoint reference. The trailing REST endpoint path is mildly redundant with readOnlyHint and earns little, but overall there is no padding.

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

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

With no output schema, the description does useful work by enumerating the returned metrics, and the fully-described 5-parameter schema covers inputs. It is reasonably complete, though it stops short of stating how the period interacts with start/end defaults or how results are ordered.

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

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

Schema description coverage is 100%, so all five parameters (website_id, start, end, segment_id, include_serp_features) are already well documented in the schema, including cross-references to wincher_list_websites and wincher_list_segments. The description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description gives a specific verb (list) and resource (competitor ranking summaries) and enumerates the returned metrics (average position, share of voice, traffic, position distribution, volume), which clearly differentiates it from wincher_list_competitors and wincher_list_competitor_keyword_positions. Sibling differentiation is implicit via the resource name rather than explicitly called out.

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

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

The phrase 'for comparison with your own' hints at the intended use case, but the description never states when to prefer this over the sibling list_competitors or list_competitor_keyword_positions tools, nor does it state prerequisites. Usage is implied rather than 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which is genuine value given there is no output schema, but it says nothing about pagination behavior, ordering defaults, or auth/access requirements beyond the raw endpoint path.

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 compact fragments, front-loaded with the resource definition before the endpoint reference. Nothing is wasted, though the telegraphic phrasing is closer to a schema comment than a sentence and the endpoint adds little for an agent that already selects tools by name.

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

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

With 100% schema coverage and no output schema, the description's enumeration of returned fields (id, domain, created_at) fills the main gap and is sufficient for correct invocation. The missing element is usage context against sibling tools, which is captured under usage guidelines rather than here.

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

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

Schema description coverage is 100%, so limit, offset, order_by, and website_id are all fully documented in the schema; baseline 3 applies. The description adds no parameter-level detail (e.g., that website_id must come from wincher_list_websites) that isn't already in the schema.

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

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

The description names the specific resource — competitor domains tracked for a website — and enumerates the returned fields (id, domain, created_at), which implicitly distinguishes it from siblings like wincher_list_competitor_keyword_positions and wincher_list_competitor_ranking_summaries that return ranking data rather than the domain roster. It lacks an explicit verb ('List') and never names those siblings, so the differentiation is inferential rather than stated.

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 closely related siblings. An agent deciding between this tool, wincher_list_competitor_keyword_positions, and wincher_list_competitor_ranking_summaries gets no help routing from the description alone.

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 and destructiveHint=false, so the safety profile is covered. The description adds the notable detail that ranking summaries are optional (a cost/behavior tradeoff), but doesn't disclose pagination, rate limits, or result size.

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 dense sentence listing returned fields plus the endpoint path; front-loaded and waste-free. The field enumeration is slightly list-heavy but earns its place.

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

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

For a read-only list tool with a fully documented schema, the description is adequate but thin: no pagination or filtering behavior is explained and there is no output schema, so consumers must infer the shape of ranking summaries and group objects.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including defaults, ranges, and the order_by syntax. The description only hints at optional ranking summaries, adding little beyond the schema.

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

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

States a specific verb+resource ('List the keyword groups of a website') and enumerates the returned fields, plus the exact endpoint. It is clearly distinguishable from wincher_get_group (single group), but doesn't contrast with wincher_list_keywords or wincher_list_segments beyond the resource name.

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

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

No when-to-use guidance, no mention of how it differs from wincher_get_group, wincher_create_group, or the sibling list tools. The only routing hint is the mention of wincher_list_segments inside the schema, not the 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 a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real behavioral context beyond them: positions are only tracked to the top 30, and include_ranking makes the call slower and return a larger payload. It does not cover pagination or rate-limit behavior, but for a read tool that is a minor gap.

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 dense sentences with the resource and its fields front-loaded, and the optional-mode caveat attached inline rather than buried. The field enumeration is long but each item earns its place as return-value disclosure in the absence of an output schema.

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

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

With no output schema and eight parameters, the description steps in to describe the returned field set and the top-30 tracking limit, which is exactly what the agent needs to interpret results. The only remaining gap is routing guidance versus the keyword-specific siblings, which is a usage concern rather than completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by spelling out what include_ranking actually returns (latest position, traffic, ranking pages, SERP features, best position in period), which the schema only summarizes as 'ranking data'. The other parameters add no description-level detail but are fully documented in the schema.

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

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

Specific verb (List) plus resource (keywords tracked for a website) with an enumeration of the returned fields. It is clearly distinguishable from siblings like wincher_get_keyword (single keyword) or wincher_list_groups. The trailing GET path reinforces the resource precisely.

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 implicitly tells the agent to set include_ranking when ranking data is needed and notes the cost tradeoff, and the schema points to wincher_list_segments for segment_id. However, it never states when to prefer this over wincher_get_keyword or wincher_get_keyword_ranking_history, nor any prerequisites beyond website_id.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that ranking data (via include_ranking) is optional and that projects group websites, but does not disclose pagination behavior or response shape beyond the field names.

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 plus the endpoint literal. It is efficient and wastes little space, though the parenthetical definition of projects is slightly tangential to invocation.

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

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

With no output schema, the description usefully enumerates the returned fields (id, name, website_ids, user_ids) and flags the optional ranking summary, and annotations cover the safety profile. It is largely complete for a zero-required-parameter list tool, with usage guidance being the main omission.

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

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

Schema description coverage is 100%, so all six parameters (end, limit, start, offset, order_by, include_ranking) are already documented in the schema. The description maps the return fields and mentions the optional ranking summary, but adds no syntax or format detail beyond the schema, 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 and resource ('List projects') and goes further by defining the resource ('folders that group websites') and enumerating the returned fields. It distinguishes itself from get-style siblings by nature of being a list operation, though it never names an alternative explicitly.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternatives are named among the large sibling set (e.g. wincher_list_websites, wincher_list_groups). The only hint is that ranking summary is 'optional', which implies usage but does not guide selection.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned field set (id, domain, country, languages, default location), which is helpful, but omits whether the list is paginated, filtered, or complete in one 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?

One front-loaded sentence carrying the resource and return fields, plus a short endpoint reference. No filler, though the trailing 'GET /search-engines' adds little for an agent that already has the 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 no parameters and no output schema, the description compensates by listing the fields a caller receives, which is enough to use the result correctly. It stops short of stating completeness/pagination behavior, but for a small static reference list that is a minor gap.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing to document and the description correctly implies a takes-no-arguments call by listing only returned 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?

The description names the resource precisely (search engines Wincher can track) and enumerates the fields returned, so an agent knows exactly what comes back. It is a static reference-list tool, clearly distinct from keyword/ranking siblings, though it never explicitly distinguishes itself from the adjacent wincher_search_locations tool.

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

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

Usage is only implied: an agent can infer this is a lookup of supported engines for identifier resolution, but there is no explicit when-to-use statement and no mention of the closely related search_locations sibling. Nothing misleading, but nothing that routes the agent either.

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 (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuine behavioral detail beyond that: by default temporary segments are included, only_named restricts to saved ones, and the underlying GET /segments endpoint is disclosed.

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

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

Three short sentences, zero filler, and the most important fact (what these are and where segment_id is used) is front-loaded. 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 trivial read-only single-parameter list with full schema coverage and safety annotations, this covers what an agent needs to invoke it correctly. It omits return-field/pagination detail, and there is no output schema to compensate, which is the only remaining gap.

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

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

Schema coverage is 100% and the only parameter is documented in the schema, giving a baseline of 3. The description adds the semantic distinction between temporary and saved segments and confirms the default behavior, which meaningfully clarifies when the flag matters.

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 the resource (saved segments) and defines it inline as "keyword filters," plus its downstream role as a segment_id source for other tools. The action verb is only implied by the title/generic listing semantics rather than stated in the body, which keeps it just short of a 5.

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

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

It gives clear context for use: these values feed segment_id in other tools, so an agent knows why to call it. It also clarifies the default-vs-only_named decision, but names no explicit alternative tool or when-not-to-use 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds the concrete field set and the fact that a ranking summary can be requested, plus the underlying endpoint, but says nothing about pagination behavior, result caps, or the cost of ranking data beyond what the schema already 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?

Purpose is front-loaded in the first clause, with the optional ranking-summary caveat and endpoint trailing it. The long comma-delimited field list is dense but informative rather than redundant; only the bare 'GET /websites.' fragment feels like 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 no output schema, the description usefully enumerates the returned website fields so the agent knows what it will receive. Pagination is handled by the schema (limit/offset), and the safety profile by annotations, leaving the definition adequate for a 7-parameter, zero-required 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 100%, so every parameter (end, limit, offset, order_by, include_ranking, include_serp_features, start) is already documented in the schema. The description only gestures at the period/ranking-summary capability, adding no syntax or format detail beyond the structured fields; 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 and resource ('List the websites tracked in Wincher') and immediately enumerates the returned fields (id, domain, display name, search engine, location, language, mobile flag, counts, competitors, brand keywords), so an agent knows exactly what comes back. This cleanly separates it from the singular sibling wincher_get_website.

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 notes that a ranking summary for a period can be included, implying the endpoint's main optional mode, but it never says when to prefer this tool over wincher_get_website, wincher_list_projects, or the competitor/ranking list siblings. Usage is implied rather than stated, so it lands at minimum-viable.

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, destructiveHint=false and openWorldHint=true, so safety is covered. Beyond that, the description adds genuinely useful behavior: results are capped at 100 and returned most-popular-first, and it notes the constraints are enforced by the API rather than the wrapper.

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 tight sentences with the scope and output shape front-loaded, followed by the parameter constraints. It repeats the 'at least 3 characters' constraint that already lives in the schema and appends a bare 'GET /locations', minor redundancy but no wasted structure.

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 return-value burden and does so by naming the returned fields, their ordering, and the 100-result cap. Safety is covered by annotations. Only edge behavior (empty results, whether the cap implies truncation or pagination) is left unstated.

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

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

Schema description coverage is 100%, so both parameters (free-text search with minLength 3, ISO alpha-2 country pattern) are already fully documented in the schema. The description restates the ISO letter-code and 3-character minimum without adding format or example detail beyond it, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Search the locations Wincher can track rankings for'), names the returned fields (code, name, country), and describes ordering and result cap. An agent can distinguish this from the nearest sibling (wincher_list_search_engines) without opening either schema.

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

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

The description states both inputs are required by the API and that search needs at least 3 characters, which implies the tool is a lookup prerequisite to setting up ranking tracking. However, it never says when to prefer this tool over alternatives or what to do when the search yields nothing, so usage is implied rather than guided.

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