Sampuli

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

No annotations are provided, so the description carries the full burden. It does disclose that the output is a listing of fields and preset scenarios, which implies a non-mutating read, but it never states explicitly that this is read-only, whether results are cached, or that the listing is scoped to a single country argument.

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 well-formed sentence that front-loads the action and enumerates representative output categories. No padding, though the trailing ellipsis is a slightly loose way to signal an open set.

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-only discovery tool with no output schema, the description conveys the shape of the return value (field names plus preset scenarios) but omits any indication of how the result should be used or which sibling consumes it. Adequate but not rich.

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

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

Schema coverage is 100% with a single required parameter whose ISO-code examples are already documented in the schema. The description's mention of country-specific fields like IBAN and SWIFT/BIC hints at what varies per country but adds no new semantics about the parameter itself.

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 clear verb (list) and resource (a country's available fields plus preset scenarios), with concrete examples of the field categories. It is reasonably distinguishable from sampuli_list_countries, which enumerates countries rather than a country's fields, though the description never names that sibling to sharpen the contrast.

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

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

There is no guidance on when to call this versus sampuli_list_countries, sampuli_list_types, or sampuli_schema, all of which sound like adjacent discovery tools. The agent must infer the entry point from the wording alone.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does explain the non-obvious internal behavior: it resolves country and field names for you (China→cn, 'SWIFT code'→swift) and emits a format-true value. It stops short of stating that the call is side-effect-free or how determinism works (the seed param is left to the schema), so it is strong but not 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?

Two sentences, front-loaded with the tool's job, then the resolution mechanic, then the sibling routing. Every clause earns its place — the example phrasings double as usable query samples.

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 supplies the essential return-value information ('generates a format-true value') and clarifies the input's semantics, which is what an agent needs to call it correctly. It could say slightly more about what a multi-count response looks like, but nothing critical is missing for a 4-parameter generator.

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

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

Schema description coverage is 100%, so the schema already documents query, seed, count, and format, making a 3 the baseline. The description reinforces the query parameter with natural-language examples and implies the resolution semantics of that input, but adds no syntax guidance beyond what the field description already gives.

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 ('Fetch synthetic test data') plus the distinguishing input mode ('from a natural request when you don't know the exact spec'). The examples and the direct routing line to sampuli_generate let an agent tell this apart from its sibling without opening either schema.

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

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

Explicitly names the condition for this tool ('when you don't know the exact spec') and the condition for the alternative ('Prefer sampuli_generate when you already have a spec like "cn.swift"'). Both when-to-use and when-not-to-use are stated with a concrete example.

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 burden, and it does disclose meaningful behavior: output is entirely synthetic, never real or registered, and passes real validators (IBAN mod-97, Luhn). This preempts privacy concerns an agent might have. It does not, however, describe output structure or the seed/count semantics, which the schema handles.

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

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

Two tight sentences, front-loaded with the core purpose and scope, then the spec grammar and the synthetic-data guarantee. No filler; 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?

No output schema exists, so the description must convey what comes back; it explains the synthetic/format-true nature of values but not the row/column shape or the json/csv distinction (the latter is in the schema). For a generation tool with five parameters it is nearly complete, missing only return-shape detail.

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

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

Schema coverage is 100% (baseline 3), and the description adds conceptual meaning beyond the schema examples by defining the selector taxonomy: a field key like 'phone', 'person' as a full coherent record, and 'preset:<key>' as a scenario. This clarifies the required spec parameter's grammar rather than merely repeating examples.

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 ('Generate ... synthetic test data for a country') that clearly distinguishes it from the list/fetch/describe/schema siblings. An agent can immediately tell this is the data-producing tool rather than a metadata lookup.

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 spec-format explanation implies when the tool is used, but there is no explicit when-to-use or when-not-to-use guidance and no naming of alternatives (e.g., sampuli_schema or sampuli_describe_country for discovering valid specs). Usage context is real but 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?

With no annotations, the description carries full behavioral burden but does reveal useful traits: a fixed, complete set of 90 entries and the ISO-code-prefix format. It does not mention whether results are cached, rate-limited, or paginated, and gives no safety or auth context.

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 tight sentence that front-loads the action, resource, cardinality, and payload meaning with 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 zero-param, read-only listing with no output schema, the description covers what the tool is, the size of the result set, and the meaning of each entry. It is nearly complete; only return-format details (e.g., plain list vs. ISO-to-name mapping) are left unspecified.

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?

Zero parameters, so the baseline is 4. The description usefully clarifies that returned ISO codes function as spec prefixes, adding semantic value even though no parameters exist to document.

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 (countries) plus the exact scope (90 countries for synthetic test data) and the practical value of each entry (ISO code as spec prefix). Issues like this make it immediately distinguishable from siblings such as sampuli_describe_country, which is a per-country lookup rather than a full listing.

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 (enumerating available countries before generating data) but never states when to call this versus sampuli_describe_country or sampuli_generate, nor any prerequisites. Context is inferable but not explicit.

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 burden, but it does disclose the returned content and the two usage modes. It does not state that the call is read-only/side-effect free, whether the list is static or paginated, or the return shape; for a zero-param listing tool those gaps are minor but real.

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 padding; the parenthetical example list carries real information rather than 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 parameters, no output schema and no annotations, the description is nearly sufficient: it identifies the content of the list and how the values are consumed. It could have named the output field or repeated that the call is read-only, but for a trivial enumeration 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?

The tool takes no parameters (empty object, 100% schema coverage), so there is no parameter semantics to explain. The baseline for a parameterless tool applies, and nothing in the description misleads about 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?

Specific verb ("List") plus a precisely scoped resource ("country-agnostic generic types") with concrete examples (uuid, enum, int, date, vin, isbn, imei, mac, email). The qualifier "country-agnostic" implicitly distinguishes it from the sibling sampuli_list_countries, so an agent can pick correctly without opening the 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?

It states the application context — the types are "usable in a custom schema or as 'any.<type>'" — which effectively tells the agent when this list is relevant. It does not explicitly name alternatives or exclusions, so it stops short of a full when/when-not statement.

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 meaningful mechanics — the two type families, example syntaxes, and that per-field 'blank' controls null probability — but omits row limits, output format behavior, auth needs, and reproducibility guarantees (seed) that an agent would want before calling.

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?

Well front-loaded: the core action leads, followed by the type taxonomy and the optional blank modifier. Two sentences with little waste, though the parenthetical type list is denser than needed.

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 dataset-generation tool with nested field objects, no annotations, and no output schema, the description covers the schema mechanics adequately but leaves out enough (usage vs siblings, output shape, count bounds) that an agent could still invoke it suboptimally.

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 75%, so most parameters are already documented. The description expands the 'type' examples (enum:, date:, de.iban) beyond the schema's inline examples, adding marginal clarity, and restates the 'blank' semantics the schema already gives. It says nothing about seed, count, or format, 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 — 'Generate rows from a custom schema' — and the body explains it mixes generic types with country-accurate fields. The 'custom schema' qualifier implicitly separates it from sampuli_generate (which likely uses preset schemas), but it never names that sibling, so the contrast 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?

There is no explicit when-to-use guidance and no mention of the alternatives. Siblings sampuli_generate, sampuli_list_types, and sampuli_list_countries are all plausibly relevant, yet the description gives no condition for choosing this tool over them.

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