surrogacyagencies

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds one genuinely useful behavioral fact — only *published* agencies are reachable — but says nothing about what happens for an unknown or unpublished slug, and no output schema exists to cover the return shape.

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

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

One short sentence with zero filler, and the lookup key is front-loaded alongside the resource. Nothing could be removed without losing meaning.

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 single-parameter read with strong annotations, the minimal description is close to sufficient, but the missing not-found/unpublished behavior and return content leave gaps that the absent output schema cannot fill. Adequate, not complete.

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

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

With a single parameter at 100% schema description coverage, the schema already defines the slug and its pattern constraints. The description adds only the word "slug" in context and no extra syntax, normalization, or case-sensitivity guidance, so baseline 3 applies.

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

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

The description names a specific verb and resource ("Get one published surrogacy agency") and identifies the lookup key ("by its slug"). The word "one" implicitly distinguishes it from the collection-returning siblings (search_listings, list_places), 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 implied rather than stated: an agent can infer this is for fetching a single known agency when the slug is already in hand, versus search_listings for discovery. There is no explicit when-not guidance or mention of what to do if only a name is known.

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 scope detail — only published entities are counted and a last-changed timestamp is returned — but says nothing about response shape or freshness semantics.

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

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

One front-loaded sentence with no filler or repetition. It is appropriately sized for a zero-parameter stats endpoint.

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 aggregate tool with rich annotations and no output schema, the description states what is counted and that a last-change time is included. It could be slightly more explicit about the returned structure (e.g., counts per entity), but it is complete enough to call 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?

With zero input parameters there is no parameter semantics to explain; baseline is 4. The description correctly does not waste space on nonexistent inputs.

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?

Clearly states a specific verb ('Get') and the resource: aggregate counts of published surrogacy agencies, places, and categories plus last-change time. The 'number of' phrasing implicitly distinguishes it from list_* siblings, but it never names those alternatives.

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 guidance, no conditions for choosing it over list_categories, list_places, or get_listing. The aggregate nature hints at its role, but the description leaves the agent to infer that.

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 the safety profile is fully covered. The description adds only that counts are included in the result; it says nothing about ordering, pagination, or whether counts are scoped to active agencies. Useful but thin beyond what annotations provide.

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 zero filler. The resource and the returned data are both stated immediately, and nothing could be trimmed 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?

For a zero-parameter read tool with full annotation coverage and no output schema, this is close to sufficient — it names the entity and the aggregate returned. Missing only minor details like result ordering or how the counts are defined.

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. Baseline 4 applies; the description correctly implies the call is unfiltered and takes no arguments.

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 categories') and adds the payload ('with their surrogacy agency counts'), so the agent knows exactly what comes back. It does not differentiate itself from siblings like list_places or list_sources, which is the only thing keeping it from a 5.

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

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

There is no when-to-use guidance, no mention of alternatives such as get_stats or list_sources, and no note on prerequisites. The agent must infer from the name alone that this is the category-browsing entry point.

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 a closed-world scope, so the safety profile is fully covered. Beyond that the description adds nothing — no statement about ordering, whether the three levels are returned hierarchically or flat, 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 redundant or filler wording; the scope qualifier follows immediately after the resource list.

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 enumeration tool with no output schema, the description covers what is listed but not how it comes back — flat names versus a country/region/city hierarchy, and the naming/format conventions used. That is the one thing an agent needs before relying on the values for subsequent filtering.

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; 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?

The description opens with a specific verb ('List') and a concrete resource set ('countries, regions and cities'), plus the qualifying domain ('that have surrogacy agencies'). It is clearly distinct from siblings like list_categories and list_sources, though it never explicitly names those siblings for comparison.

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 or when-not-to-use guidance, and no link drawn to search_listings or get_listing, which are the tools an agent would plausibly use these place values with. An agent must infer that this is a facet/enumeration lookup.

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 annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. Beyond that, the description adds useful output context by saying each source includes license and refresh information, which is especially valuable because no output schema is provided. It does not describe ordering or pagination, but the annotation coverage lowers the burden.

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 description is a single well-structured sentence that front-loads the core purpose and then adds the two key source attributes. There is no unnecessary wording or repetition.

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

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

For a simple zero-parameter read-only listing tool with strong annotations and no output schema, the description covers the essential purpose and names the main returned fields. It could be slightly more complete by mentioning whether the list is paginated or ordered, but no major gap prevents correct invocation.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline score is 4. The description does not need to compensate for any schema gaps.

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

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

The description uses a specific verb, 'List,' with a clear resource, 'where the surrogacy agency data comes from,' and further specifies that each source includes license and refresh information. This distinguishes it from sibling tools like get_listing, search_listings, list_categories, and list_places, which handle different resources.

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 the tool is used when an agent needs provenance or source metadata, but it does not explicitly state when to choose this tool versus alternatives, nor does it mention exclusions or prerequisites. For a zero-parameter metadata listing tool this is minimally adequate, but there is no explicit routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is fully covered. The description does add one genuine behavioral fact beyond them — that only "published" agencies are returned, implying drafts/unpublished records are excluded — but it says nothing about result volume, typo-fallback matching, or error behavior for uncovered countries.

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 efficient, though the brevity edges toward under-specification rather than optimal density.

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 eight optional parameters, a fully described schema and no output schema, the structured fields carry most of the burden, so the description is not required to explain returns. Still, for a faceted search tool it omits the key operational facts an agent needs — that all filters are optional, how facets combine, and when to prefer a sibling lookup tool.

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

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

Schema description coverage is 100%, so every parameter (including the cursor/pagination contract and the sort defaults) is already documented in the schema. The description's "by text, place and category" merely maps loosely onto q, the place slugs and category, adding no format, precedence, or combination rules beyond what the schema states.

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

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

The description names a specific verb and resource ("Search published surrogacy agencies") plus the three facets it searches over (text, place, category). That is enough to tell it apart from get_listing (single item), list_places/list_categories/list_sources (lookup tables) and get_stats, 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 when-to-use or when-not-to-use guidance: nothing says to call this before get_listing, or which of the three facets is required versus optional. The only signal is the verb "Search", which leaves the agent to infer the routing decision entirely from the sibling names.

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