Lilambd Data for Agents

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

With no annotations, the description carries the burden and does substantial work: it discloses per-call pricing ($0.005 USDC), the x402 payment mechanism and where the payment payload goes (_meta["x402/payment"]), and that sample=true caps results at 3 free rows. It does not describe response shape, error behavior, or rate limits beyond the limit/offset params.

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?

Front-loaded with identity and use cases, then the routes, then the payment/free-tier caveat — a sensible priority order. The route listing is dense shorthand but each clause is load-bearing; nothing is 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?

Given a nested params object, no output schema, and no annotations, the description covers invocation and cost well but says nothing about what data comes back for each route (fields, row limits on paid calls, error responses for invalid codes). Enough to call it, not enough to fully predict its 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?

Schema coverage is 100%, so the baseline is 3, and the description adds real value beyond the schema by mapping which parameters belong to which route and marking lat/lon as required on /nearby. It still leaves parameter value formats (e.g. what 'type' accepts) to inference.

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 resource (airport data) and enumerates the three callable routes with their parameters, so an agent knows exactly what the tool exposes. It does not explicitly differentiate itself from sibling API tools, but the airport domain is unambiguous against siblings like colors, markets, or exchanges.

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 route list implies the selection rule: /nearby for lat/lon proximity, /search for query/country filters, /{code} for a direct lookup. The asterisk on lat/lon signals required parameters and the sample hint tells the agent how to try it without paying. No explicit exclusions or 'use X instead' guidance is given.

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 and does well on the hard parts: it discloses that calls cost $0.005 USDC via x402 in _meta["x402/payment"] and that sample=true yields a free 3-row preview, which is essential pre-call information an agent cannot get from the schema. It omits error behavior, default page sizes, and result shape, which keeps it below a 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?

The route list and payment terms sit in one dense block and are front-loaded well enough, but the audience enumeration ('design tools, games, generative art, e-commerce filters and AI assistants') is pure marketing and does not help an agent decide or call. Roughly one sentence of the text does no work.

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 nested-params tool with no annotations and no output schema, the description supplies the non-obvious essentials: the four routes, their parameter names, the cost model, and the free preview escape hatch. It stops short of describing what a successful response contains or how failures/unknown names behave, which is the main 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?

Schema coverage is 100%, so the baseline is 3; the description exceeds it by mapping parameter names to specific routes (count for /random, q/limit/offset for /search, hex/limit for /nearest) and by explaining the paid-vs-sample switch, which the generic 'params' object schema does not. The required-parameter marker on /nearest's hex is implied but never stated explicitly.

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 the resource concretely ('30,000+ Named Colors', 'give every color a human name') and enumerates the four callable routes, so an agent knows this is a color-name lookup API rather than the many unrelated data APIs among its siblings. The audience blurb ('great for design tools, games...') adds flavor but no additional discrimination.

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?

Routes are given with their key parameters inline — '/random (count); /search (q, limit, offset); /nearest (hex*, limit); /{name_or_hex}' — which is effectively the when-to-use decision an agent needs, since route selection is the only real choice here. There is no explicit statement of exclusions or limits (e.g., what happens with an unknown hex), but the context is clear.

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 does disclose the two behaviors an agent most needs: a paid call at $0.005 USDC per request via x402 (_meta["x402/payment"]) and a free 3-row preview via sample=true. It omits rate limits, error/failure behavior when payment is missing, and what a response looks like, 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?

Front-loaded with the resource, then routes, then commercial terms — an efficient ordering with no filler. The semicolon-dense route/pricing sentence is slightly run-on but every clause carries operational 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?

Payment mechanics, the free sample escape hatch, and per-route parameters cover the call-time essentials. But with no output schema, no annotations, and a nested 'params' object, the description never says what a returned record contains (fields, granularity, pagination semantics of limit/offset), leaving a meaningful gap for an agent composing a 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?

Schema coverage is 100%, so a baseline of 3 applies, but the description adds real value beyond the schema by enumerating which query parameters each route accepts (year/level/by/limit/offset for /top, from/to for /countries/{iso2}), which the schema's generic 'params' object does not convey. It stops short of explaining the meaning of ambiguous params such as 'level' and 'by'.

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 dataset ('Armed Conflict Events by Country and Region') and characterizes it as 'clean yearly conflict numbers', which tells an agent exactly what resource this returns. It is clear and concrete, but it never contrasts with the many sibling data APIs (notably the similarly-named 'regions' tool, which could be confused with the /regions route).

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 lists the three routes and their parameters plus use-case audiences ('risk dashboards, travel-safety apps, news tools'), which implies usage. However, there is no explicit when-to-use / when-not guidance, no guidance on choosing /top vs /regions vs /countries for a given question, and no disambiguation from the sibling 'regions' tool.

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

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

With no annotations, the description carries the burden well: it discloses the paid model ($0.005 USDC per call via x402, payment passed in _meta["x402/payment"]) and a free 3-row preview mode, which are non-obvious operational facts an agent must know before calling. It does not cover pagination behavior, error/payment-failure handling, or result 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?

Three compact sentences: identity first, then routes, then cost/free-preview escape hatch. No filler, and the actionable cost information is where a caller will look for 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 3-parameter dataset lookup with no output schema, the description covers resource scope, route selection, searchable fields, cost, and a free preview path — enough to invoke correctly without further reading.

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%, but the schema only lists route values generically; the description enumerates the actual search query keys (q, country, status, category, limit, offset), which meaningfully exceeds the schema. The 'sample' and _meta payment semantics are also clarified beyond the schema's one-line hints.

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 resource ('Stock Exchanges and Trading Venues (MIC)') and a clear lookup action, with target audiences (fintech apps, trading bots, data pipelines) that set the domain. It is unambiguous against siblings like airports or markets, though it never explicitly says how it differs from markets/regions.

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?

Names both routes and their use conditions ('/{mic}' for a specific venue vs '/search' with q/country/status/category/limit/offset), and gives a concrete fallback for cost-sensitive calls ('set sample=true for a free 3-row preview'). No explicit when-not-to-use guidance or pointer to a sibling for related 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?

With no annotations, the description carries the full burden and does disclose two high-value behaviors: a paid $0.005 USDC cost per call via x402 (_meta["x402/payment"]) and a free sample=true 3-row preview. It omits what happens on payment failure, whether unauthenticated calls error, and the response shape, keeping it short of a 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?

The critical facts — what the data is, the routes, the price, the free preview — are front-loaded in one dense paragraph with no repeated sentences. The 'for real-estate tools, relocation apps, local-business dashboards and AI agents' clause is marketing filler that does not help the agent act.

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 multi-route gateway with nested params and no output schema, the description does the important work: it names all four routes with their parameters and discloses cost plus the free preview escape hatch. The main residual gap is that nothing describes the returned payload or pagination semantics, which matters more here since no output schema exists.

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%, so the baseline is 3, but the description goes further by enumerating each route's accepted query parameters (indicator*, year, prefecture, order, limit, offset; q for /municipalities; indicator for /municipalities/{code}) and marking indicator as required with an asterisk. It still leaves the meaning of indicator codes and limit/offset defaults 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 resource (official statistics for every Japanese municipality) delivered as a JSON API, which clearly separates it from the dataset-oriented siblings like airports, colors, or power. It does not explicitly contrast itself with any sibling, but the dataset subject is unambiguous.

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 route list implies which endpoint to call for ranking, indicator listing, municipality search, or single-municipality lookup, which is useful implied guidance. However, nothing states when to use /rank versus /municipalities, what an 'indicator' is, or any exclusions, so the agent must infer the routing decision.

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 behavioral burden and does well: it discloses the paid cost ($0.005 USDC per call), the x402 payment metadata key, and the free sample=true preview. It does not cover rate limits or error behavior, but the critical cost and access mechanics are transparent.

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 core content is dense and front-loaded with the tool's purpose, but it includes marketing-like phrasing ('Data that grounds what people ask AI about feelings, fortune, love and daily life') and runs multiple route listings together. It is functional but not maximally concise.

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 complex multi-route tool with no output schema, the description comprehensively covers inputs and payment. However, it does not describe what the responses look like, leaving an agent to infer return shapes for ten distinct endpoints. This is a meaningful gap given the tool's breadth.

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%, so the baseline is 3, but the description adds substantial value by listing each route with its required (asterisked) and optional parameters, e.g., /sun (lat*, lon*, date, tz). This goes well beyond the schema's generic route and params object.

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 tool provides computed calendars, holidays, and helplines, listing specific data types and ten routes. It doesn't explicitly differentiate from sibling tools, but the domain is distinct enough that an agent can tell what it does.

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 route list implies when to use each endpoint (e.g., /holidays for holidays), but there is no explicit guidance on when to choose this tool over alternatives or when not to use it. The usage is inferable but not spelled out.

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 does disclose the most consequential trait: paid $0.005 USDC per call via x402 through _meta["x402/payment"], plus a free 3-row sample escape hatch. It does not cover response shape, error behavior, or rate limits, which keeps it short of a 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 dense sentences: identity, routes/params, then payment and sample. Front-loaded with the resource and nothing repeated. The list of consumer use cases (localisation tools, language-learning apps, games, AI pipelines) is mild filler but occupies only one clause.

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 a nested params object and no output schema or annotations, the description covers routing, filter names, placeholder substitution, cost, and the free preview — enough to invoke correctly. The remaining gap is what a returned language record contains, which the description only gestures at with 'language metadata'.

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%, so the baseline is 3, but the description adds real meaning: it enumerates the /search query parameters (q, country, family, endangerment, limit, offset) that the schema only alludes to via a generic params object, and clarifies that {code} is a placeholder to substitute (e.g. /HND).

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 the resource (World Languages, Glottolog) and the concrete data it returns (language metadata for localisation, learning apps, games, AI pipelines), plus the two routes it exposes. An agent can distinguish it from siblings like regions or airports by domain, though the description never frames the operation as a verb (search/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?

Names the two routes and the filter parameters that belong to /search, which implies when to use which route, and calls out sample=true as the free-preview path. There is no explicit routing advice (e.g. use /search when you have a partial name, /{code} when you have an ISO/Glottolog code) and no comparison to sibling data APIs.

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 provided, the description carries the behavioral burden and does well by disclosing the paid x402 model ($0.005 USDC per call) and the free 3-row sample preview. It does not explicitly state read-only safety, error behavior, or response characteristics, so it falls short of a 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?

The description is compact and front-loaded: resource identity comes first, followed by routes, payment details, and preview behavior. Every sentence contributes useful selection or invocation information 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?

The description covers routing, search parameters, payment, and free preview well, which is important given there are no annotations. However, with no output schema and no stated return shape, error behavior, or payment failure handling, an agent still lacks some context needed to interpret results confidently.

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%, so the baseline is 3, but the description adds useful route-specific parameter meaning by listing /search query fields (q, osi_approved, limit, offset) and explaining sample=true. It does not fully document parameter types or edge cases, but adds real value beyond the generic params object in 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?

The description names a specific resource (Open Source Licenses / SPDX) and makes its domain clear against unrelated sibling tools like airports or colors. It implies retrieval via route listing and use cases, but never states an explicit verb such as 'get' or 'search', keeping it 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?

It provides clear usage context by naming target consumers (dependency scanners, SBOM tools, package registries, AI agents) and listing available routes. It also explains the free preview via sample=true, but does not explicitly say when to choose /{id} versus /search or when not to use the tool.

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

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

With no annotations, the description carries the burden, but the tool is a zero-parameter read-only listing, so risk is inherently low and the verb 'List' makes the read nature clear. The 'Free.' prefix usefully discloses cost, but there is no mention of response size, pagination, or rate behavior for what could be a large index of APIs.

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 with no waste, and the cost note is front-loaded before the action. Everything an agent needs is in the first clause.

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, annotation-free listing tool with no output schema, the description adequately covers what it returns (APIs, routes, query parameters). It stops short of telling the agent how the result should be used to pick among the sibling data tools, which is the one 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 the baseline is 4. The description's note that listed APIs include routes and query parameters describes the payload rather than inputs, which is helpful context but not required for invocation.

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 all Lilambd data APIs') and adds what the listing contains (routes and query parameters), which is more than a restatement of the name. It does not explicitly differentiate itself from the many data-category siblings (airports, colors, markets, etc.), though the plural 'APIs' implies this is the discovery/index tool.

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 entry point for discovering what Lilambd offers before calling a specific data tool, but the description never says so or names any sibling as an alternative. No exclusions or preconditions are given.

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 present, the description carries the full burden and does well: it discloses the paid access model ($0.005 USDC per call via x402), the free 3-row preview via sample=true, the implicit default filter behavior, and data provenance/licensing. It omits error behavior, rate limits, and any authentication beyond the payment header, keeping it short of a 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?

The description is dense but front-loaded: the core concept comes first, then the locality taxonomy, then default behavior, then routes, then payment. Every sentence carries information. The route list runs together in one block, which slightly hurts scannability, preventing a 5.

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-output-schema, nested-params tool spanning five routes, the description supplies the taxonomy, the route map with required params, the default filter, and the payment/preview mechanics. The main gap is any indication of the response shape (fields returned per market) — reasonable to omit but would have closed the loop.

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%, so baseline is 3, but the description earns above baseline by enumerating per-route parameter sets with required markers (lat*, lon*, q*, country*) and defining the locality enum values (big_city/city/regional/remote with km thresholds). It still does not explain the semantics of limit/offset or the shape of the params nested object beyond the schema example.

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

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

The description states a specific resource and scope: 'markets away from big cities,' tagged by distance-from-city locality bands, with an explicit route inventory. An agent knows exactly what data domain this covers. It stops short of naming the sibling 'markets' tool as the alternative, so the boundary between the two is only implied rather than explicit.

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 discloses a meaningful default ('default answers return only regional and remote markets'), which tells the agent what happens if it does nothing, and it lists route options. However, there is no explicit when-to-use-this-vs-'markets' guidance and no statement of when a route like /near should be preferred over /search. Usage is inferable but not directed.

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 present, the description carries the full burden and does substantial work: it discloses the paid model ($0.005 USDC per call via x402 and the _meta["x402/payment"] field) and the sample=true free 3-row preview cap. That is exactly the kind of cost/side-effect context an agent needs before invoking. It says nothing about rate limits, error behavior, or response 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?

Purpose is front-loaded in the first sentence, followed by audience, then route/parameter reference, then payment terms — a sensible ordering. The route list is dense but each token is load-bearing. Slight cost: the route grammar strings are hard to parse on a single line and the 'travel apps, local-discovery apps, maps, games' audience list is marketing 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 multi-route gateway with nested `params`, no output schema, and no annotations, the description covers purpose, route selection, per-route parameters, and the paid/free-preview mechanics — enough to call it correctly. Missing only return-format expectations and what errors look like when payment is absent.

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%, so the baseline is 3, but the description adds value the schema cannot: it maps which query parameters belong to which route (lat*/lon* for /nearby, q/country/kind/offset for /search, min_population/sort for /countries), plus the star marking required lat/lon. The schema only describes `params` as a generic string map, so this routing detail is genuinely additive. It omits value formats and allowed values for kind/sort.

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 resource ('World Markets: Farmers, Flea, Night and Fish Markets') and an explicit verb-plus-outcome ('Find real-world markets anywhere'), so an agent knows exactly what domain this covers. It never names a sibling tool, but the resource is distinctive enough in the list (airports, colors, exchanges, etc.) 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?

Enumerates the five routes with the parameters each accepts, which effectively tells the agent which entry point fits 'look up by id', 'browse kinds', 'find nearby', 'text search', or 'browse by country'. It also states the cost and the free-preview escape hatch, which is real decision-relevant guidance. It stops short of explicit when-not or alternative-tool routing.

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

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

With no annotations, the description carries the burden and discloses important behavioral details: paid calls at $0.005 USDC per call via x402 and a free 3-row preview via sample=true. It does not cover return shape, pagination behavior, or error handling, but the payment and preview constraints are the key non-obvious traits.

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 dense but front-loaded and largely earns its space by packing purpose, use cases, route parameters, payment, and preview into a compact block. The semicolon-separated route list is information-rich but slightly hard to scan.

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 the multi-route complexity, lack of annotations, and no output schema, the description adequately covers routes, key parameters, payment, and sample mode. However, it leaves gaps around response structure, pagination, allowed route parameter values, and error 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?

Schema coverage is 100%, so the baseline would be 3, but the description adds meaningful route-specific parameter mappings such as /nearby needing lat*, lon*, kind, and form, and /nonprofits/search supporting revenue and cause filters. It still does not define allowed values or formats for many fields like kind, form, or sort.

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 defines the resource as a world directory of organizations such as research bodies, societies, funders, and publishers, explicitly excluding companies and governments. The route list makes the available operations concrete, so an agent can distinguish this tool from sibling datasets like airports, regions, or markets.

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 clear usage contexts including research tools, grant finders, CRM enrichment, maps, education apps, and AI agents, and notes that the directory excludes companies and governments. It does not explicitly compare against alternative sibling tools or give when-not-to-use guidance, but the tool-level usage context is clear.

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 behavioral burden and usefully discloses the paid $0.005 USDC per-call x402 mechanism and the free 3-row sample preview. It does not cover rate limits, error behavior, or return shape, but the cost and preview behavior are significant additions.

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 front-loaded with the resource name and packed with useful route, parameter, payment, and sample information without filler. Every sentence contributes directly to correct invocation.

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 route-based directory tool with no annotations and no output schema, the description covers purpose, routes, query parameters, payment, and free preview adequately. It could say more about return format, but given the schema coverage it is sufficiently 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 description coverage is 100%, so the baseline is 3, but the description adds meaning by enumerating /search query parameters (q, category, country, limit, offset) and clarifying the /categories and /{wikidata} routes. This goes beyond what the route schema alone provides.

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 identifies the resource as an 'Online Platforms Directory' and lists the available routes (/search, /categories, /{wikidata}). It distinguishes the domain from sibling tools like airports or colors, though it does not explicitly contrast behavior with those siblings.

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 concrete use cases (market research, competitor maps, onboarding flows, AI agents) and lists the routes, which tells an agent when this tool is relevant. It does not give explicit when-not-to-use guidance or name a preferred alternative for overlapping needs.

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 does disclose two critical behaviors: paid access at $0.005 USDC per call via x402 payment metadata, and a free sample=true path capped at 3 rows. That is exactly the kind of cost/precondition context an agent needs before invoking. It does not cover error behavior, rate limits, or auth failure modes, keeping it short of a 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?

Dense and front-loaded: identity, routes, pricing, and the free-preview escape hatch all arrive in a compact block. The middle clause listing target audiences ('energy apps, climate tools, maps, simulations, city-building games and AI agents') is pure filler that earns no place for an agent consumer.

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 nested multi-route gateway with no output schema, the description supplies the route inventory, per-route parameters, and payment mechanics — enough to call it correctly. What's missing is any sense of the response shape or the meaning of edge syntax like the 'lat*' marker, but those are secondary for a 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 coverage is 100%, so the baseline is 3, but the description adds real value by mapping which parameters belong to which route (lat*, lon*, fuel, min_mw, limit for /nearby; q, country, fuel, min_mw, limit, offset for /search) — information absent from the generic 'params' object schema. The unexplained asterisk on 'lat*' and the absence of units on min_mw are minor 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?

States a specific resource (global power plant data) and enumerates the five concrete routes, so the agent knows the tool's actual capability surface. It doesn't need to differentiate against siblings like 'airports' or 'exchanges' since the domain is self-evident, but the opening tagline ('Power Plants of the World') is branding rather than a verb+resource statement.

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 audience list (energy apps, climate tools, games) hints at use cases, and the route enumeration implies what each sub-query does, but there is no explicit guidance on when to pick /nearby over /search, and no when-not-to-use or prerequisite statement. An agent must infer route selection from parameter names 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?

With no annotations, the description carries the full burden and does well: it discloses that calls cost $0.005 USDC via x402, where the payment goes (_meta["x402/payment"]), and that sample=true yields a free 3-row preview. It stops short of describing rate limits, error behavior, or response shape, but the pricing/payment disclosure is unusually valuable.

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 scope is front-loaded and the routes and payment terms follow in compact form. There is minor padding in the marketing clause 'ready for dropdowns, maps, games and analytics,' which does not help an agent decide or invoke.

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 data-lookup tool with no output schema and no annotations, the definition covers scope, routes, key parameters, cost, and a free-preview escape hatch. The main missing piece is what a returned region record looks like, but the trigger conditions for using it correctly are otherwise present.

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 already 100%, so the baseline is 3; the description earns extra by naming the concrete search parameters (q, country, sort, limit, offset) that the query object accepts, which the schema only hints at via an example. It does not explain the ISO 3166-2 format in prose, leaving that to the schema's example.

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

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

The description states a specific resource ('Every first-level administrative region on Earth') plus an added data component ('Land Stats'), which is unambiguous and easily distinguished from siblings like airports, markets, or languages. The verb+resource framing is concrete enough that an agent knows exactly what domain data this returns.

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 lists the two routes and the search query parameters, which implies how to call it for listing vs. a single lookup. However, it never states when an agent should prefer this tool over a sibling or when-not to use it; usage is inferred from route structure rather than explained.

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 at all, the description carries the full burden and does meaningfully well: it discloses the $0.01 USDC per-call cost, the x402 payment mechanism and exactly where the payment proof goes (_meta["x402/payment"]), and the existence of a free 3-row preview via sample=true. What it omits is anything about response shape, pagination, or failure/refund behavior on a paid call.

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?

Front-loaded with the core value proposition, then routes, then pricing — a sensible order for an agent scanning for cost and capability. It is dense and slightly telegraphic in the route listing, but no sentence is 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 3-parameter tool with a nested params object, no annotations, and no output schema, the description covers payment, preview, and route semantics well enough to call it correctly. It stops short of explaining what a returned 'daily answer' looks like or the meaning of route-specific params like 'theme' and 'table.'

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%, so a 3 would be the baseline, but the description goes beyond the schema by attaching query parameters to specific routes (/today takes table, theme, limit; /history takes since*, table, theme), which the schema does not enumerate. The asterisk on 'since*' is left unexplained, a minor 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 states a specific resource and framing: a daily delta of "what jumped since the previous measured day across open software and world events," explicitly contrasted with "raw data." That is far more informative than the bare name 'rising.' It does not, however, differentiate itself from any of the single-word sibling tools (markets, exchanges, platforms, etc.), which all look like data APIs.

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 context is implied through the route enumeration (/days, /today, /{date}, /history) and the note that this is "a daily answer, not raw data," which nudges the agent away from per-record queries. There is no explicit when-to-use/when-not-to-use guidance and no sibling tool is named as an alternative, so the agent must infer selection from the route list.

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 does well: it discloses the paid model ($0.005 USDC per call via x402), the payment location (_meta["x402/payment"]), and the free 3-row preview flag. It omits response shapes and error behavior, which keeps it short of a 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?

Purpose is front-loaded, then the route menu, then the payment/preview note — no filler. The route enumeration is dense and list-like but each entry carries routing value, so it stays efficient.

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 multi-route, route-dispatched API with no output schema and a nested params object, the description covers the routes, their key parameters, cost, and preview mode. It stops short of describing return shapes or error handling, but the essential calling information is present.

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%, so the baseline is 3. The description does add per-route parameter listings (/convert takes value*, from*, to*; /search takes q, quantity_kind, limit, offset), which supplements the free-form 'params' object whose additionalProperties only say string — useful but mostly restating discoverable route docs rather than explaining semantics like format or required-vs-optional beyond asterisks.

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 resource and capability ('Unit Converter and Physical Constants') and distinguishes itself from the sibling API wrappers (airports, colors, exchanges) by naming the domain of 'unit maths'. The enumerated route list makes the tool's scope concrete 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?

The route list with per-route parameters gives clear guidance on which internal endpoint to select for a given need (search vs convert vs constants vs isotopes). It does not explicitly state when to prefer this tool over a sibling, but the self-evident domain split (units vs airports vs colors) makes that inferable.

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