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

No annotations are supplied, so the description carries the full burden; it does at least imply a read-only browse operation and discloses an important behavioral bound ('the page lists up to 40', limit 1..40), which prevents pointless limit values. It does not cover pagination beyond the single page, whether results are ranked by rating, rate limits, or whether an unknown city returns empty versus error.

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?

It is a single dense paragraph with the resource description front-loaded and semicolon-separated per-parameter notes, so an agent can scan it quickly with zero filler sentences. The only waste is the enumerated list of return fields, which duplicates information already carried by the 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?

For a three-parameter list tool with an output schema, the description covers the resource, all three parameters with examples and bounds, and the page-size limit. Return values are covered by the output schema, so the field listing is a bonus rather than a necessity; nothing needed to call the 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?

Schema description coverage is 0%, so the description must compensate, and it does for all three params: service_slug gets a concrete example, city is marked optional with a slug example ('istanbul'), and limit gets an inclusive range tied to the underlying page size. The remaining gap is that the schema default of 10 for limit is not restated and there is no note on whether city accepts display names versus slugs only.

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: 'Top professionals for a service', and enumerates the returned fields (name, city/district, bio, rating, review count, profile URL). This is clearly distinct from the sibling tools (search_services, service_detail, faq, price_guide, trending_services), which all operate on services rather than professionals, although the description never names those alternatives explicitly.

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

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

Usage is implied rather than stated: 'Top professionals for a service' plus an optional city filter tells an agent roughly when this fits, and the service_slug example ('ev-temizligi') shows the expected input style. There is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives for city-wide browsing, and no statement about what happens when the city has no matching pros.

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 no annotations supplied, the description carries the full burden; it does disclose key behavioral facts an agent needs — currency (TRY), the 12-month window, the national default when city is omitted, and the shape of the returned data. It does not address whether data is cached/live, any rate limits, or error behavior for an invalid slug, so the read-only safe-lookup profile has to be inferred.

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 no filler; the payload contents are front-loaded and the parameter guidance is appended where an agent looks for it. The dense enumeration is long but each item conveys distinct returned data, so it earns its space.

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?

Both parameters are explained despite zero schema coverage, and an output schema exists so return values need not be spelled out — yet the description still summarises them usefully. The remaining gap is sibling differentiation, which matters given four other armut_* tools that could plausibly return price or pro information.

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 must compensate, and it largely does: it gives a concrete service_slug example ('ev-temizligi') and explains that city is an optional slug ('adana') defaulting to all of Türkiye. The only shortfall is that it does not say how to obtain a valid slug or what happens if one is wrong.

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 — a price guide for a service — and enumerates exactly what it contains (page-listed min/max price in TRY, 12-month averages with quote counts, pro count, rating, example jobs, reviews). That is well beyond a restatement of the name, but it never explicitly contrasts itself with siblings such as armut_service_detail or armut_list_pros, which likely overlap on pricing and pro 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?

Usage is implied by the content list plus the city default ('default: all Türkiye'), which tells an agent how to get national vs city-level results. There is, however, no explicit when-to-use guidance and no statement of when another sibling tool would be the better 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?

With no annotations, the description carries the full behavioral burden. It does disclose matching semantics (Turkish or ASCII input, matches names/slugs rather than descriptions) and enumerates returned fields, which is useful context. It says nothing about limit behavior, result ranking, case/diacritic handling, or pagination, which an agent needs to invoke it predictably.

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 compact block, front-loaded with the action and resource, then query semantics, then return shape. Every clause carries information; the only cost is density — the return-value parenthetical is packed into the same run-on sentence rather than separated.

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 the description did not need to enumerate return fields (though it helpfully does). It covers the hard part — multilingual query matching — and its only real omission is `limit`, which leaves the agent guessing about result-size control for a 6,759-item catalogue.

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 must compensate. It handles `query` well (language/encoding tolerance, concrete Turkish examples, what the string is matched against) but leaves `limit` completely unexplained — no mention of its default of 10 or its effect on result volume.

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 ('Search Armut's service catalogue ... by keyword') and scopes it with the catalogue size and matching target (service names/slugs). It also signals the entry-point role ('use the slug with the other tools'), which implicitly separates it from armut_service_detail and armut_price_guide, though no sibling is named 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?

'Use the slug with the other tools' tells the agent this is the starting point of a workflow, which is genuine when-to-use guidance. It stops short of stating when NOT to use it — e.g. browsing by popularity (armut_trending_services) or when a slug is already known — so there is no explicit alternative routing.

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 no annotations supplied, the description carries the full burden. It does useful work by disclosing the returned fields and the downstream dependency on service_id, and read-only behavior is implied by 'detail'. However, it says nothing about authentication, rate limits, failure modes for invalid slugs, or whether a single record is always returned.

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

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

Two sentences, front-loaded with what the tool returns and followed by the single parameter's meaning and discovery path. No filler; the parenthetical about the price guide earns its place by linking to a sibling workflow.

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

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

For a one-parameter read tool with an output schema, this is nearly complete: the description covers purpose, the parameter's format, and its role in the broader workflow, so the output schema handles return structure. Only edge-case behavior for invalid or missing slugs is left 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 description coverage is 0%, so the description must compensate, and it does: it explains that service_slug is a slug string, provides a concrete format example ('ev-temizligi'), and tells the agent where to find valid values. It does not specify error behavior for unknown slugs, but the semantic gap is largely closed.

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

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

The description opens with a specific verb-and-resource: fetching the detail of one service, and enumerates exactly which fields come back (name, description, pro count, rating, review count, service_id). It also implicitly distinguishes itself from armut_search_services, which it names as the lookup path for slugs, though it never states the sibling boundary directly.

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 concrete workflow context by naming armut_search_services as the way to obtain a valid service_slug and flagging that service_id is needed for the price guide, so an agent knows how this tool fits between discovery and pricing. It stops short of stating when not to call it or listing alternative routes explicitly.

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?

No annotations are supplied, so the description carries the full burden. It discloses the data source, which is a small plus, but says nothing about whether the lookup fails on unknown slugs, whether a service may have zero FAQs, rate limits, or auth requirements. For a tool with zero annotation coverage this leaves notable behavioral gaps.

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 no filler, and the resource definition is front-loaded ahead of the parameter hint. The parameter note is somewhat awkwardly appended inside the description rather than integrated, which keeps it just short of top marks.

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

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

The tool is simple: one required parameter and an output schema that already documents return values, so the description does not need to explain the response shape. It is still missing how to source a valid slug and any failure/empty-result behavior, which are the remaining things an agent needs 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 coverage is 0%, so the description must compensate, and it does partially by giving a concrete slug example ("ev-temizligi"), which signals the expected lowercase, hyphenated, Turkish format. It does not explain how to obtain a valid slug (e.g. from armut_search_services) or what happens with an invalid one.

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 clearly ("frequently asked questions for a service, with answers") and its provenance (the service page's FAQ schema), so an agent knows what data comes back. However, it is a bare noun phrase with no verb and no differentiation from sibling armut_service_detail, which plausibly also returns service-page content. Adequate but not sharply distinguishable.

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 when-not, and no mention of alternatives such as armut_service_detail or armut_price_guide. The agent must infer that this is the right call when a user asks service-specific FAQ questions, and must guess whether to use it alongside or instead of the detail tool.

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?

No annotations are provided, so the description carries the full behavioral burden. It does describe the data surfaced, but says nothing about the read-only nature, data freshness, result limits, pagination, or whether the 'most-searched' section is derived or real-time.

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 with the key concept front-loaded and the return contents enumerated in parentheticals. It earns its words, though the long run-on with embedded parenthetical lists is slightly harder to scan than a short bulleted 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 an output schema present, the description needn't restate return shapes, and with zero parameters there is no input ambiguity to resolve. For a low-risk read-only trending fetch the coverage is close to sufficient; only the absence of any behavioral note (freshness, scope, no auth) keeps it short of 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is empty and fully 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 front-loads a specific resource and scope: 'What's popular on Armut right now', then enumerates the three things returned (service groups, trending services with pro counts/ratings/reviews, most-searched city+service combos). That clearly separates it from armut_search_services and armut_service_detail by topic, though it never names those siblings 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 statement and no named alternative. Usage is only implied: the 'what's popular right now' framing suggests discovery/browse scenarios rather than targeted lookups, which the agent must infer.

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