apostilles

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 is covered structurally. The description still adds genuine value with the "published only" scope and the explicit exclusion "Exam questions and answers are never returned" — a meaningful data-boundary disclosure. It stops short of describing behavior on missing inputs or error outcomes.

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

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

Two short sentences, front-loaded with the action and resource, followed immediately by the data-exclusion caveat. Nothing redundant or 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?

For a one-parameter read tool with full annotations and no output schema, the description adequately covers what is returned and what is deliberately withheld. The only gap is behavior for a nonexistent or unpublished slug, which an agent would want to know.

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 slug parameter already carries a pattern, length bounds, and description. The description only restates lookup-by-slug and adds the published-only filter implication, which is close to the baseline for a fully documented 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 and resource ("Get one published academy course by its slug") and even enumerates the payload contents (objectives, lessons, FAQ). The singular "one ... course" implicitly contrasts with the listing siblings such as list_courses, but no sibling is actually named, so it falls 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?

The word "published" signals that only live courses are retrievable, which is a partial when-to-use constraint. There is no explicit guidance on when to prefer this over list_courses or a search sibling, nor what to expect for an unpublished or unknown slug.

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

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

The description adds a crucial behavioral constraint, specifying that the tool fetches a 'published' authority. This scope limitation is not present in the annotations or schema, thus adding necessary context to the AI agent.

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

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

The definition is a single, powerful, and declarative sentence that gets straight to the point without any wasted words.

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

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

Given that the annotations confirm it is a safe, read-only, and idempotent operation, and the description defines the resource and retrieval method precisely, the definition is complete for an agent to make an accurate decision.

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

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

The schema description coverage is 100%, meaning the structured data fully defines the parameter. The description only adds semantic meaning to the overall operation tied to that parameter.

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

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

The description clearly states the action ('Get one'), the specific resource ('published apostille authority'), and the identifier used ('by its slug'). This is highly specific and easy to distinguish from sibling tools like search_listings.

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

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

The description clearly defines the scope—retrieving a single entity based on its unique identifier. While it doesn't explicitly state 'when not to use this,' its precision relative to sibling search tools provides sufficient context for usage.

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 genuinely new information by stating the response includes the product's page and outbound link, which matters because there is no output schema. It omits not-found behavior, which keeps it below 5.

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

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

A single front-loaded sentence with no filler; the lookup key and the returned content are both stated in one pass.

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 full annotation coverage and complete schema documentation, this is nearly sufficient. The only real gap is what happens when the slug does not resolve, which an agent would want to know.

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 slug parameter carries its own description plus a pattern, so the schema does the heavy lifting. The description's 'by its slug' restates rather than extends that, matching the 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?

States a specific verb and resource ('Get one affiliate product') and scopes it to a single-item lookup, which implicitly contrasts with the plural sibling list_products. It does not explicitly name the alternative tool, so it stops short of a 5.

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

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

'by its slug' implies the precondition that the caller already has a slug, which is useful context for choosing this over list_products or search_listings. However, no explicit when-to-use/when-not statement or named alternative appears.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds value by sketching the response payload (three counts plus last-change time), which is useful given there is no output schema, but it says nothing about format, units, or whether counts and timestamps come from the same snapshot.

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 sentence, no filler, and the payload contents are front-loaded before the timestamp clause. Every clause carries information an agent needs.

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

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

For a zero-parameter, read-only, non-destructive tool with full annotation coverage, the description supplies enough: what is counted and that a freshness timestamp is included. A note on the response shape or whether unpublished records are excluded would close 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the scope is fixed and global ('published' entities across the catalogue).

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 ('Get the number of') and the exact resources counted: published apostille authorities, places and categories, plus a last-changed timestamp. That implicitly separates it from the list_* and search_listings siblings, which enumerate records rather than aggregate them, 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?

Usage is only implied: an agent can infer this is the tool for summary counts rather than record retrieval. There is no explicit 'use this when you need totals instead of listings' statement and no alternatives are named.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds one piece of value beyond that – that the payload includes apostille authority counts – but says nothing about ordering, size, or whether the list is exhaustive.

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. Every word carries information: the verb, the resource, and the salient content of each returned item.

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 zero-parameter listing tool with rich annotations and no output schema, this is essentially sufficient. A brief note on ordering or typical list size would close 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?

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline for a zero-parameter tool applies, with no missing parameter information to compensate for.

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

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

States a specific verb ('List') and resource ('categories') and adds a scope detail: each entry carries apostille authority counts. It is clearly distinct from the siblings (list_places, list_sources, search_listings), 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?

Usage is only implied by the tool's name and purpose – fetch the category vocabulary. There is no statement of when to prefer this over get_stats or search_listings, nor any preconditions. For a zero-parameter read this is tolerable but bare.

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 by structured data. The description adds two genuinely new facts beyond that: only published courses are returned, and each record includes level, length, pass mark and certificate validity. It does not mention ordering or what happens at the limit boundary, so it adds context without being rich.

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 sentence, front-loaded with the verb and scoped resource, then the returned fields. Every clause earns its place and there is no redundant restatement of the 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?

For a two-parameter, zero-required read tool with complete annotations, the definition covers scope (published only) and return fields, which matters because no output schema exists. The remaining gap is result ordering and whether the 50-item cap implies truncation, which an agent might want to know before listing.

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 the level enum and limit bounds (1-50, default 50) fully documented in the schema. The description's mention of 'level' marginally reinforces the filter but adds no syntax, default, or pagination semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and a precisely scoped resource (published academy courses), plus the fields each result carries. It is clearly distinguishable from get_course (single item) and the unrelated list_* siblings, 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?

Usage is only implied: the agent can infer this is the browse-all path as opposed to get_course for a single course, and that the optional level parameter narrows results. There is no explicit 'use this when' or exclusion statement, and nothing about what to do if no courses match.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description contributes the meaningful scoping fact that only places with apostille authorities are returned, but says nothing about ordering, size, or whether the list is static.

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

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

A single front-loaded sentence with no filler; the scoping condition is attached directly to the resource it constrains. Nothing is wasted.

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

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

For a zero-parameter, read-only reference list with annotations covering safety and no output schema, the description gives enough to call it correctly. It stops short of stating the return shape (e.g., whether places carry identifiers usable in later calls), which would help an agent chain calls.

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 for the description to compensate for; the baseline for a parameterless tool 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 countries, regions and cities') plus a scoping qualifier ('that have apostille authorities'), so the agent knows exactly what set is returned. It does not explicitly name or differentiate against siblings like list_categories or list_sources, but the resource domain is distinct enough that confusion is unlikely.

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: this is clearly the reference/lookup call for geographic entities that support apostilles. There is no explicit 'use this when...' or 'do not use for...' guidance, and no mention of alternatives for retrieving individual place details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, non-destructive and closed-world, so the safety profile is covered. The description's contribution beyond that is that results include product counts — useful, but no ordering, pagination, or empty-result behavior 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?

A single short sentence with zero filler, and the key payload detail (counts) is front-loaded where the agent will read it.

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

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

For a zero-parameter, read-only listing tool with full annotation coverage, the description plus schema is enough to invoke it correctly. Minor gap: with no output schema, the exact return shape (field names, ordering) is only alluded to.

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 there is no parameter semantics to explain; the baseline for a zero-param tool 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 the product categories') plus a distinguishing payload detail (product counts). However, it does not differentiate itself from the sibling 'list_categories', leaving an agent to guess which category lister to call.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The only implied cue is that this variant returns counts, which the agent must infer rather than being told.

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 fully covered. The description adds one genuinely non-obvious data semantic — the price is a point-in-time snapshot from the day the product was checked, not a current price — but says nothing about result volume, ordering, 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 short sentences, zero filler, with the core action and the most decision-relevant detail (price snapshot semantics) front-loaded ahead of the filter note.

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-optional-param, read-only list tool with full schema coverage and annotations, the description is largely sufficient and even hints at the returned fields (product + price). The one gap is the absence of any output schema combined with no note on pagination or result limits.

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 optional parameter carries its own type, slug pattern, and length bounds. The description only restates that the parameter filters by category, adding no syntax or behavior beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the affiliate products") plus the returned payload (price as of the check date) and the filter dimension. It implicitly separates from get_product (single record) and list_categories, but never names a sibling, so the differentiation is left to 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?

"Filter by product category" plus the optional parameter implies narrowing usage, but there is no explicit when-to-use guidance and no mention of when to prefer get_product, list_product_categories, or list_categories instead. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered elsewhere. The description adds that each row includes a license and a refresh cadence, which is useful content context, but says nothing about ordering, pagination, or whether the source set is static.

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 sentence, front-loaded with the resource and immediately followed by what each entry contains. Nothing is wasted and nothing essential is deferred.

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 listing tool with no output schema, the sentence covering what each source entry contains (license, refresh) is close to sufficient. A note on list size or ordering would close 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies an unfiltered, full-list call with no arguments needed.

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

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

Specific verb ('List') plus resource ('where the apostille authority data comes from' / sources), and it names the fields each entry carries (license, refresh). No sibling tool overlaps this provenance role, so the agent can distinguish it from get_stats or list_categories 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?

Usage is implied rather than stated: an agent infers this is the tool for provenance/licensing questions. There is no explicit when-not condition or pointer to alternatives such as get_stats for aggregate data.

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 by structured data. The description adds one useful scope fact — only *published* authorities are returned — but says nothing about pagination, empty-result behavior, or typo fallback, all of which are only visible in the schema and cursor param text.

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 with zero filler and the key facets front-loaded. It is efficient but arguably under-specified rather than deliberately terse — nothing is wasted, yet little is added.

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 8 optional parameters and no output schema, the description is the only place to explain the search result shape and paging loop, and it does not. The schema compensates for filter semantics, so the definition is workable, but an agent gets no narrative on what a hit looks like or how to continue past the first page.

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 one of the 8 parameters is already fully documented (slug sources, sort defaults, cursor reuse rules, country 400 behavior). The description itself contributes no additional parameter meaning beyond naming the three facet types, 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 (Search) plus the resource (published apostille authorities) and the three facet types used to filter (text, place, category). An agent can distinguish this from get_listing (single item) and the list_* siblings, though the description never names those alternatives explicitly and the 'listings'/'authorities' naming mismatch requires a small 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 statement of when to use this versus get_listing, get_stats, list_places or list_categories; the agent must infer routing from the tool names alone. The only routing hints ('from /places', 'from /categories') live in the schema descriptions, not in the tool description itself.

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