ABC Remonty Oleba

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

Annotations already cover readOnly/idempotent/destructive/openWorld, but the description adds genuine behavioral traits beyond them: it is 'deterministic' and 'missing facts are reported, never guessed.' That no-hallucination contract is meaningful context an agent can rely on when interpreting the answer bundle.

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, front-loaded with the core action and its sources, with the behavioral contract trailing. No wasted words, though the second sentence slightly duplicates the read-only annotation.

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 16-parameter tool with no output schema and only 50% parameter coverage, the description is thin - it does not explain the shape of the returned bundle, the effect of mode/fallback_mode, or how the many filters interact. An agent can call it but cannot predict the output or the fallback behavior.

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

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

With 16 parameters and only 50% schema description coverage, the description must compensate for the undocumented half, but it mentions no parameter at all - not mode, fallback_mode, price_limit, allow_fallback, or the area range fields. The schema carries the load and leaves notable gaps the description does not fill.

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 ('compose') and resource ('source-linked answer bundle') and names the four underlying sources (service catalog, cennik, service-area evidence, realization portfolio). This clearly positions it as the synthesis tool relative to granular siblings like get_prices/get_realizations, 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?

The description implies usage ('compose a bundle' from multiple sources) but gives no explicit when-to-use or when-not guidance, and does not tell the agent to prefer this over calling search_site, get_service, or get_prices individually. Usage is inferred 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 cover safety (readOnly, non-destructive, idempotent, not open-world). The description adds a critical interpretive behavior: absence of public evidence is not proof that Oleba refuses a locality. That is valuable context beyond annotations, though it does not cover auth, rate limits, 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?

Two sentences with no filler, and the caveat is front-loaded. The structure is compact, though the first sentence is abstract rather than action-oriented.

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

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

For a tool with two required params, an optional limit, and no output schema, the description omits return values, parameter semantics, and when to use it. It supplies one important interpretive rule but leaves the agent with major 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%; none of service, location, or realization_limit are described in the schema. The description adds no parameter meaning at all—it never mentions what service or location should be, nor what realization_limit controls. It 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 conveys the semantic intent—distinguishing a documented offer from a published realization—but never states the concrete action (e.g., 'checks whether...') or what the tool returns. An agent cannot tell exactly what check_service_area does from the description alone, though the title supplies some clarity.

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

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

There is no indication of when to use this tool versus siblings like get_service, get_realizations, or ask_oleba. It only states an epistemic caveat, leaving the agent to infer the appropriate context entirely.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds real value beyond them by disclosing the refusal policy for protected/unpublished/noindex items and by naming the three output representations, which is exactly the kind of context an agent needs.

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

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

Two sentences, zero filler. The core action and accepted identifier forms come first and the refusal constraint second, so the most important information is front-loaded.

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

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

For a simple read-only tool with no output schema, the description covers what is returned (Markdown/text/metadata) and what is rejected. It could have noted that the URL must be same-site/canonical on oleba.pl or pointed to a discovery tool, but nothing critical 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 coverage is 50%: the identifier param is documented while format is only an enum with a default. The description restates the accepted identifier forms (numeric ID, slug, same-site URL) and echoes the three format values, but adds little syntax or meaning beyond what the schema already conveys.

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: resolve a single public WordPress item and return Markdown/text/metadata. The scope word 'public' and the plural/singular distinction implicitly separate it from siblings like search_site and list_services, though no sibling is named.

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 a useful when-not clause (password-protected, unpublished, noindex content is refused), which is more than most tools. However it never tells the agent how to obtain the identifier or points to search_site as the discovery alternative, so the 'when to use vs alternatives' guidance 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds that only 'public' pages/posts are returned, which is useful scoping, but it says nothing about the result cap (limit max 10) or what a result item contains.

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

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

A single front-loaded sentence that states the action, the resource, and the scoping concept with zero filler. The example list is dense but each item earns its place by illustrating valid inputs.

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

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

For a two-parameter read-only lookup with annotations covering safety and no output schema, the description is adequate but thin: it never states that results are a bounded list, nor how 'location' is matched (exact locality vs. free text). Nothing critical is missing, but an agent must guess at result shape.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does add real value by enumerating valid locality examples (Piaseczno, Ursynów, Mokotów, Józefosław, Konstancin-Jeziorna), clarifying the expected 'location' format, but the 'limit' parameter is entirely unexplained.

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 (find) and resource (public Oleba pages/posts) scoped to a locality, which is clearer than the terse title 'Find Oleba local pages'. It does not, however, distinguish itself from plausible siblings like search_site or get_content, leaving overlap for the agent to infer.

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

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

The description offers no when-to-use guidance, no exclusions, and never names an alternative such as search_site or get_content. The locality examples imply a location-scoped lookup, but the agent gets no signal about when this tool beats a general site search.

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 destructiveHint=false, so safety is covered. The description adds real value by disclosing that results are informational excerpts rather than a binding quote, but says nothing about matching behavior, result limits, or empty-result handling.

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 with zero filler, and the tool's scope is front-loaded before the results caveat. Every clause earns its place.

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

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

For a one-parameter read tool without an output schema, the description covers what the tool searches and the non-authoritative nature of results. It is still incomplete on the key ambiguity of how it differs from get_prices and what an excerpt actually contains.

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

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

Schema description coverage is 100% and the single query parameter already documents its purpose, length bounds and concrete examples. The description's phrase 'a service or phrase' only loosely echoes this, 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 clear verb and resource: find context for a service or phrase on the public pricing page. However, it never distinguishes itself from the sibling get_prices, which an agent would reasonably assume returns the same thing, so sibling differentiation is missing.

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 no when-to-use guidance and names no alternatives, even though get_prices and ask_oleba are obvious competing choices. The 'not a binding quote' caveat hints at a use case (informational lookups) but does not actually route the agent between 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, closed-world. The description adds useful framing: prices are public informational ranges, not binding offers, which is a 'what you get' caveat not in the annotations. It doesn't cover pagination, ordering, or limits, so it earns a modest 3.

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 purpose, then the optional-query note, then the disclaimer. No wasted words, though the disclaimer could be phrased more compactly.

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?

Reasonable for a simple read-only two-parameter tool. The disclaimer is a nice touch. However, without an output schema the description should say what 'structured rows' contain and how results are ordered or limited, and it doesn't.

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%: query has an inline description with examples, limit has none. The description only notes query is optional, adding little beyond the schema. Baseline for the high-coverage parameter is met, but limit semantics (max, default) are left entirely to 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 ('Parse') and resource ('public renovation cennik') and the output ('structured rows'). It doesn't differentiate from siblings like get_price_information or ask_oleba, but the resource and output format are clear.

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?

Says 'Query is optional' but gives no when-to-use or when-to-prefer-alternatives guidance. The sibling get_price_information is notably similar and never referenced, leaving the agent to guess between them.

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, closed-world behavior, so the safety profile is covered. The description adds value beyond that by enumerating the response shape (project metadata, evidence, media links, optional machine-readable content) and flagging that the post is 'public', which is a meaningful access constraint.

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

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

A single sentence that front-loads the action and the scope before listing outputs. No filler, 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?

With no output schema, the description usefully enumerates the returned fields, which is the right thing to carry. It omits error behavior for missing/private posts and the effect of include_content, but for a 2-parameter read tool this is close to complete.

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

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

Schema coverage is 50%: 'identifier' is documented in the schema as ID/slug/canonical URL, but 'include_content' has no schema description. The phrase 'optional machine-readable content' partially explains what include_content controls, but it does not clarify the default or the cost/size tradeoff.

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 ('Resolve') and resource ('one public realization/gallery post'), plus the scope of what is returned. The word 'one' implicitly separates it from the plural sibling get_realizations, but it never names that sibling, so differentiation relies on inference.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as get_realizations (list) or search_site. The reader must infer from 'one' that this is the single-item lookup path.

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=true, idempotent=true, destructive=false and closed-world, so the safety profile is covered. The description adds non-obvious behavioral context beyond that: only published site content is searched and private customer records are never accessed, plus the demotion/exclusion behavior of the underlying search. It omits return shape/ordering, but for a read tool the added privacy and content-policy detail is substantive.

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, front-loaded with the core verb+resource, then the exclusion policy, then the privacy boundary; nothing is redundant with the title or schema. It could have spent one of those sentences on the parameters instead, but 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?

For a 12-parameter, all-optional search tool with no output schema, the description should say more about result shape, ordering and paging relative to the hard limit/max of 10, and about which filters are ANDed together. It covers the content-policy dimension well but leaves the mechanics of invoking a many-filter search underspecified.

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 50%: six parameters (tag, mode, scope, service, object_type, initial_state) already carry their own descriptions, while year, limit, query, location and the two area bounds do not. The description only gestures at the axis of filtering ('by locality and/or topic'), adding no format, unit, or interaction guidance (e.g. whether tag and service combine, how query differs from scope). Baseline 3 is the right ceiling given the schema does half the work and the description does not close the other half.

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 (search) and resource (public Oleba project/gallery realization content) and scopes it by locality/topic. It is clear what an agent gets, though it never distinguishes itself from the singular sibling get_realization or from search_site, so the agent must infer search-vs-fetch 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?

It provides real selection context: generic service pages, local landing pages and price-list pages are 'intentionally demoted or excluded', which tells the agent this is not the tool for price or landing content. However, it names no alternative tool (e.g. get_realization, get_price_information) the way the calibration's top example does, so routing between siblings is still 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 establish read-only, idempotent, non-destructive behavior, but the description adds real value beyond them: the exact payload format and MIME type, the renderer/openUrl capability requirement, and that text links accompany the resource. It stops short of describing payload size or failure behavior when the renderer is unsupported, so not a full 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 sentences, front-loaded with the hard usage gate, then the deliverable, then the routing alternative. No filler and nothing repeated from annotations 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?

The host-capability requirement and the contrast with get_realizations cover the highest-risk failure mode, which is the main thing an agent needs. However, with 11 loosely documented parameters and no output schema, an agent still has to infer which filters behave like the sibling tool and how to construct a valid A2UI request.

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 11 parameters and only 45% schema description coverage, the description needs to carry weight, but it only mentions 'optional location' and 'no writes'. The other parameters (scope, service, object_type, area bounds, initial_state) get no semantic clarification beyond their schema text, leaving the coverage gap unfilled.

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 concrete verb and deliverable: returns self-contained A2UI v0.9.1 Basic Catalog messages as an application/a2ui+json embedded resource, plus text links. It also names what the search is based on ('same public realization search'), which lets an agent distinguish it from get_realizations without reading 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?

Explicit gating ('Use ONLY when an A2UI-capable host or the user explicitly requests A2UI'), an explicit alternative ('For normal gallery requests use get_realizations (MCP Apps)'), and the prerequisite for the alternative (renderer supporting this catalog and openUrl). Both the when and the when-not 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that lookup works from a stable id or a natural-language phrase, but says nothing about failure behavior when resolution misses, or about how the optional limits affect results.

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 the verb first and zero wasted clauses; the return payload is enumerated compactly rather than padded with 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 names the returned sections, and annotations cover the safety profile. But for a 4-parameter resolver with only 50% parameter documentation, the missing behavior on unresolved names and the meaning of the two limit parameters leaves an agent with real 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 50%: identifier and location are documented in the schema, while price_limit and realization_limit are bare. The description partially compensates by tying 'price rows' and 'related realizations' to the output, implying those limits control them, but it adds no syntax, range, or format detail beyond the schema.

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

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

States a specific verb (resolve) and resource (a service) plus the exact return payload (primary public page, structured price rows, related realizations). It is clearly distinguishable from list_services, get_realizations, and get_price_information 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?

The description implies single-service lookup and even hints that the identifier accepts either a stable id or a natural-language phrase, which is useful context. However, it never states when to prefer this over list_services, get_price_information, or get_realizations, and gives no prerequisites or 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=false, so the safety profile is fully covered. The description adds the useful fact that the return payload covers identity plus machine-readable and MCP endpoints, but says nothing about format, size, or freshness/latency, and there is no output schema to fill that 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?

A single sentence, front-loaded with the verb and the payload contents, with no filler or redundant restatement of the title. Every clause earns its place.

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

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

For a zero-parameter, read-only tool whose annotations carry the safety profile and with no output schema, the description covers the essential what. It is nearly complete, with only minor gaps around endpoint format and when in a workflow to call it.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies a no-argument, site-wide call.

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') and enumerates the resource categories: public site identity, machine-readable endpoints, and MCP endpoint information. It is clearly distinguishable from content/sibling tools like get_content or list_services, though it does not explicitly contrast itself with them.

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

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

No explicit when-to-use or when-not-to-use guidance is given. The intent (a discovery/overview entry point) is strongly implied by the name and the enumerated payload, but an agent is left to infer that this should be called before other site tools or when site identity is needed.

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 safety and determinism are covered. The description adds that the catalog is 'curated' and 'public', implying a fixed, non-user-scoped dataset, but it says nothing about the 20-item cap or how results are ordered or paged.

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

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

A single front-loaded sentence with no filler or redundancy. It is slightly over-adjectived ('curated', 'stable', 'canonical'), but every clause still points at what is returned.

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

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

With no output schema, the description must carry the return contract, and it does sketch the shape (service objects linked to canonical content). It is still silent on result count limits, ordering, and pagination behavior, which an agent needs to call this correctly given the capped limit 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?

There is one parameter ('limit') with 0% schema description coverage; the schema supplies only type, default, maximum, and minimum with no prose. The description never mentions the limit, its cap of 20, or whether the catalog is paginated, so it does not compensate for the missing schema documentation.

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') and resource ('the curated public Oleba service catalog'), which an agent can distinguish from the singular sibling get_service. However, the trailing clause about 'stable machine-readable service objects linked to canonical public content' is marketing-flavored jargon that adds little definitional precision.

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 no indication of when to call this tool versus get_service, search_site, or check_service_area, all of which operate on the same domain. There is no mention of prerequisites, when the catalog is appropriate, or when a more targeted sibling is preferable.

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, non-destructive, closed-world). The description adds genuinely useful behavior beyond that: it discloses the return payload (canonical URLs, titles, excerpts, match diagnostics, machine-readable representation URLs) and that ranking is locality-aware — information the agent cannot get anywhere else since there is no output schema.

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 with zero filler; the search scope and the ranking approach are front-loaded, and the return payload follows immediately. Every clause earns its place.

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

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

For a three-parameter read-only search with no output schema, the description covers the essentials: what corpus is searched, how results are ranked, and what the results contain. The remaining gap is the undocumented limit/content_type semantics, which belong more to the schema than the prose.

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 33%: query is documented, but limit and content_type carry no schema descriptions. The description adds nothing about these parameters — it does not explain the 1-10 limit, the default of 5, or the meaning of the any/page/post enum, so it 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?

States a specific verb (Search) and resource (published public WordPress pages/posts on oleba.pl) with a clear scope constraint (public content only). It distinguishes itself from mutating siblings like get_content by being a search entry point, but never names which sibling to prefer when a direct lookup would work.

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 alternatives are named, despite 11 siblings including the obviously competing ask_oleba, get_content and list_services. The agent must infer that this is the free-text entry point while the others are direct-lookup tools.

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