Read-only tools over Ranked, a Nigerian business directory with dated regulator register snapshots
Scored across 10 tools
Most tools have clearly distinct purposes (find_business vs place vs rankings vs hubs vs stats), but compare_places and ranked_compare have near-identical names for different domains (business listings vs products), which risks misselection. ranked_check_licence and ranked_by_regulator also overlap somewhat, though one is name-based and the other lists register entries, so boundaries remain readable.
Nine tools use the ranked_ prefix consistently (ranked_place, ranked_rankings, ranked_check_licence, etc.), giving a predictable pattern. The outlier compare_places lacks the prefix, which is a minor but notable deviation.
10 tools is well-scoped for a business ranking/directory server, with each tool covering a distinct capability (search, detail, rankings, comparisons, regulator checks, hubs, stats). No redundancy that would bloat the surface.
The surface covers search, lookup, ranked lists, comparisons, regulator/licence checks, payment research, hub citation and provenance stats, giving solid lifecycle coverage. Minor gaps exist (e.g. no explicit category taxonomy or batch listing browse beyond hubs), but core workflows are covered.
Two business listings side by side, by slug (the tail of https://ranked.ng/place/). A record, not a recommendation: the answer carries each side's displayed rank, Ranked score and six-dimension breakdown on their SHARED published category-city facet, Google rating/review count as source data, the evidence-only verified tier, distance_km between the two listings, and dimension_leads: per dimension which side scores higher on Ranked's published breakdown, with a gap under tie_band_points (5) reported as "even". It never picks a side and never infers rank from score. same_facet=false when the two are not on one category and city (scores are then not comparable and dimension_leads is null); an unpublished facet answers { published: false, reason }. The cite url is the pair page https://ranked.ng/vs// when both sides sit inside its rendered window, else the ranking page.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | first place slug, e.g. 'eko-hotels-and-suites-a1b2c3' | |
| b | Yes | second place slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description goes much further, disclosing that it never picks a side nor infers rank from score, defines the tie_band_points=5 'even' rule, explains same_facet=false incomparability, unpublished facet responses, and the cite URL selection logic.
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 opening sentence front-loads the core action, and the remaining dense clauses cover output, edge cases, and URL behavior. Given the absence of an output schema, the length is largely earned, though the semicolon-heavy single paragraph could be structured more readably.
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 carries the full burden and details every returned field: rank, Ranked score, six-dimension breakdown, Google rating, verified tier, distance_km, dimension_leads, and cite URL. It also covers edge cases like same_facet=false and unpublished facets, so an agent has enough to invoke and interpret the 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?
The schema fully documents both slug parameters with examples, so baseline is 3. The description adds the exact slug format as the tail of https://ranked.ng/place/<slug> and ties the validity of the comparison to the two places sharing a category-city facet, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific comparison operation ('Two business listings side by side, by slug') and scopes it to a published category-city facet. It also clarifies it returns a record rather than a recommendation, which distinguishes it from generic compare tools, but it does not explicitly name a sibling like ranked_compare or ranked_place to guide selection.
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 by the opening line: compare two listings by slug. The description adds conditions on when the comparison is meaningful (same_facet, unpublished facet), but it never states when to choose this tool over ranked_compare, ranked_place, or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the entries on a Nigerian regulator's register (CBN, SEC, NAICOM, NCC, PenCom) as accessed on the snapshot date, optionally filtered by licence-class text, in the register's own order (the regulator's order, not a ranking). Source is the regulator's own publication; the licence class is as the regulator states it. Each row carries the register's statement, hub_url, feed_url and place_url where Ranked has a matching listing. A register row is what the regulator's register listed on the access date. It is not a licence finding by Ranked, registers lag revocations, and absence from Ranked's copy is not proof that a name is unlicensed.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| category | No | filter on licence class / scope text, e.g. 'microfinance', 'broker', 'ISP', 'PFA' | |
| regulator | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only, idempotent, and non-destructive. The description adds useful transparency about snapshot-date access, the regulator's own ordering, returned URLs, and explicitly clarifies that this is not a Ranked licence finding.
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 structured and mostly efficient, but the final disclaimer about not being a licence finding is repeated with similar wording earlier. Still, it remains readable and front-loads the core action and scope.
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 helpfully states that each row includes the register's statement, hub_url, feed_url, and place_url where applicable. It also defines what a register row is. Minor gaps remain around response shape and pagination details, but the core context is covered.
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?
Only the 'category' parameter is described in the schema; 'regulator' has an enum but no explanatory text, and 'limit'/'offset' are left implicit. With 25% schema coverage, the description partially compensates by explaining the category filter but leaves standard pagination and regulator semantics underspecified.
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 the verb 'List' and the resource 'entries on a Nigerian regulator's register', with the regulator and optional licence-class filter. It also distinguishes itself from a ranking by noting the register's own order, separating it from ranking tools.
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?
Explains optional filtering and the source/order semantics, but does not explicitly say when to prefer this tool over siblings such as ranked_check_licence or ranked_rankings. The guidance is implicit rather than a direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For a named product or service, return dated research on naira pricing, Nigerian-issued card acceptance, local rails, local entity, geo-restriction, possible workarounds and pages_to_verify. These are snapshot observations, not a current payment guarantee: availability and limits depend on the product, issuer and account. Missing evidence is returned as 'unknown'.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | product or service name, or its domain |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that results are dated snapshot observations rather than a current payment guarantee, that availability depends on product, issuer and account, and that missing evidence is returned as 'unknown'. This adds meaningful interpretive context without contradicting the annotations.
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 core action and deliverables followed by the two critical caveats (snapshot not guarantee; unknown for missing evidence). Every clause earns its place 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?
Complete for a single-parameter research tool: input condition is stated, return contents are enumerated in lieu of an output schema, and the caveat/unknown-handling behavior is disclosed. Annotations already carry the safety profile.
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's 'named product or service' only echoes the schema's 'product or service name, or its domain' and adds no new format, example, or constraint detail.
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 verb and resource: return dated research for a named product or service, scoped to Nigerian payment feasibility with enumerated deliverables (naira pricing, card acceptance, local rails, geo-restriction). The title frames the exact question answered, and the topic clearly differentiates it from siblings like ranked_check_licence and ranked_find_business.
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 opening 'For a named product or service' states the trigger condition, and the deliverable list makes clear which questions it answers. Alternatives are not named and no when-not-to-use exclusions are given, but the topical separation from siblings is evident from their names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a Nigerian business name appears on a regulator's own register — CBN, SEC, NAICOM, NCC or PenCom — as accessed on the snapshot date, and under what licence class. Exact normalised-name match first, then partial. Each match carries the register's statement ("Appears on the register as accessed on ..."), the hub_url, the JSON feed_url, and place_url when Ranked has a matching indexable listing. A register row is what the regulator's register listed on the access date. It is not a licence finding by Ranked, registers lag revocations, and absence from Ranked's copy is not proof that a name is unlicensed. Ranked never says "licensed" in its own voice.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | business name as on the offer, policy or app | |
| limit | No | ||
| regulator | No | any |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description openly discloses that registers lag revocations, absence from Ranked's copy is not proof of unlicensed status, Ranked never says 'licensed' in its own voice, and that results reflect the snapshot date. It also reveals match ordering and the exact payload fields, which is exemplary transparency.
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 every sentence earns its place: purpose, match behavior, result contents, and critical limitations. It is front-loaded with the main purpose and uses later sentences for necessary caveats without repetition or fluff.
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 and no nested objects, the description does a strong job of explaining what each match carries (statement, hub_url, feed_url, place_url) and what a register row means. It falls slightly short by not describing no-match behavior, how the limit parameter shapes results, or how the 'any' regulator option behaves.
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 only 33%, so the description must compensate. It adds useful context for the name parameter (normalised exact match first, then partial) and indirectly for regulator by listing CBN, SEC, NAICOM, NCC and PenCom. However, the limit parameter is never explained, and its effect on result pagination or count is left entirely 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?
The description states a specific verb ('Check whether... appears'), a concrete resource (a Nigerian business name against regulator registers), and explicitly names the five regulators and the licence-class outcome. It is very clear, but it does not explicitly distinguish itself from siblings such as ranked_by_regulator, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and its caveats, but it never says when to use this tool instead of a sibling, when not to use it, or what prerequisites apply. No alternative tool is mentioned, so an agent gets no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare 2-5 named products or services on Nigeria-usability: naira pricing, card acceptance, local entity, geo-restriction. Rows are returned in the order given — Ranked does not rank them here. Ranked Technologies operates some listed products; those carry operated_by_ranked=true, are returned in a separate unranked block, and are never ordered above others (Rule 1). Evidence tier is provenance, not quality.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial behavioral context beyond them: input order is preserved, Ranked-operated products are partitioned into a separate unranked block, are flagged with operated_by_ranked=true, and are never ordered above others. The note that evidence tier indicates provenance rather than quality is also meaningful and non-obvious.
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 information-dense. Every sentence earns its place: core operation, count constraint, comparison dimensions, ordering behavior, operated-by-Ranked handling, and evidence-tier semantics. There is no filler or redundancy.
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 tool has a single parameter and no output schema, but the description covers the essential invocation semantics and the important behavioral quirks, including the special handling of Ranked-operated products. The annotations cover safety and idempotency, so the overall picture is complete enough for an agent to call this tool 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?
The schema has no parameter descriptions and 0% coverage, so the description is the sole source of semantic meaning. It explains that the names parameter accepts 2-5 named products or services, specifies the comparison dimensions, and clarifies that the order of the names array controls output row order. This fully compensates for the bare 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 uses a specific verb ('Compare') and a specific resource ('products or services on Nigeria-usability'), and it names the four concrete criteria (naira pricing, card acceptance, local entity, geo-restriction). It also differentiates itself from ranking tools by explicitly stating that rows are returned in the given order and not ranked.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool when you need to compare 2-5 named products or services on Nigeria-usability. It does not explicitly name sibling tools as alternatives, and it lacks an explicit when-not-to-use statement, but the trigger conditions are clear and no alternatives are wrongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Ranked's file-backed dataset of Nigerian-relevant businesses, institutions, websites and apps (6519 entries: 3860 on a regulator register, 1290 with domain/app-listing evidence, 1369 unverified candidates). Categories are source/research labels, not live ranking eligibility. Results carry source and snapshot date, plus source and canonical URLs where available; register-backed results carry the register's entry and access date. For live rankings and place pages use ranked_rankings / ranked_place. Ranked Technologies operates some listed products; those carry operated_by_ranked=true, are returned in a separate unranked block, and are never ordered above others (Rule 1). Evidence tier is provenance, not quality.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | name, domain, category or licence type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool read-only, idempotent, and non-destructive. The description goes well beyond this by disclosing dataset composition and counts, result fields like snapshot date and source URLs, the separate unranked block for operated_by_ranked items, Rule 1 ordering behavior, and the 'evidence tier is provenance, not quality' 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?
The description is dense but every sentence earns its place: it front-loads the core purpose, then covers dataset scale, result semantics, sibling routing, and behavioral rules. It repeats no schema details and contains 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?
With no output schema, the description compensates by specifying what results carry, including source and snapshot dates, URLs, register access dates, operated_by_ranked flags, and ordering constraints. For a simple two-parameter read-only search tool, this is complete enough for 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 schema documents query well but leaves limit undocumented, giving 50% coverage. The description enriches query meaning by clarifying that categories are source/research labels rather than ranking eligibility, but it adds nothing about the limit parameter or how matching works beyond the schema's phrase 'name, domain, category or licence type'.
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 opening sentence clearly identifies a search operation over a specific dataset and lists the result types ('Nigerian-relevant businesses, institutions, websites and apps'). It also differentiates itself from siblings by stating that live rankings and place pages belong to ranked_rankings / ranked_place.
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 explicitly routes live-ranking and place-page use cases to ranked_rankings / ranked_place, providing a clear when-not-to-use signal. It does not distinguish against all siblings, but the main search-vs-live distinction is explicit and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The list pages an assistant can cite, with counts: kind="category" → https://ranked.ng/ hubs with the number of cities that have a published ranking with exact-category matches; kind="city" → https://ranked.ng/city/ hubs with matching published categories; kind="state" → https://ranked.ng/state/ hubs (only states with at least 25 operational listings); kind="data" → the regulator-register hubs, the operator-listed EV charging directory, their JSON feeds and the open-data index (file-backed, no database needed). These are coverage counts, not a claim that search engines index every URL.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=true and idempotentHint=true, so no safety ambiguity exists. The description adds valuable behavioral detail beyond that: counts are exact-match coverage counts, state hubs require at least 25 listings, data hubs are file-backed and need no database, and the coverage counts do not guarantee search engine indexing.
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 core purpose and then uses a compact semicolon-delimited list to cover all four kind variants without redundancy. The closing caveat about coverage counts vs. search-engine indexing is meaningful and prevents misuse rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description gives enough context to call it correctly: all kind values, their URL shapes, count meanings, and the file-backed data behavior. Combined with the annotations carrying the read-only/idempotent safety profile, an agent has what it needs to select and invoke the tool appropriately.
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 schema description coverage at 0%, the description compensates strongly by defining every kind enum value with concrete URL templates and selection criteria. However, the limit parameter is never mentioned in the description, so the compensation is partial even though the schema already documents its default and bounds.
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 exactly what the tool provides: public hub list pages with coverage counts, broken into kind-specific URL patterns. The detail for each kind—category, city, state, data—makes the tool's purpose concrete and distinguishes it from the other ranked_* siblings that serve business checks or rankings queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear selection context for each kind value, telling the agent which URL form and inclusion criteria apply. It does not explicitly name alternative tools or say when not to use ranked_hubs, so it stops short of full sibling routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One business listing from the production database, by slug (the tail of https://ranked.ng/place/) or by name + city. Returns name, category, city, state, address, phone (business phones are public), website, Google rating/review count, the evidence-only verified tier, its rank on its primary PUBLISHED facet if any, regulator-register matches (with 'as accessed on' provenance), the canonical url, data_as_of (Google listing fetch date when supported; otherwise null), profile_evidence separating listing fetches, review publication and analysis dates, source_facts with dated source citations, and observations: the dated record of what changed on the listing (name, address, phone, website, business status, opening hours), newest first, each with the source that reported it. Places that are not OPERATIONAL are excluded unless includeClosed=true.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | city slug or name (used with name) | |
| name | No | business name (used with city when slug is absent) | |
| slug | No | place slug, e.g. 'abbey-mortgage-bank-plc-k5mjcu' | |
| includeClosed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the read-only, idempotent, non-destructive safety profile, so the description's job is to add operational behavior — which it does abundantly: non-OPERATIONAL places are filtered out unless includeClosed=true, observations are returned 'newest first, each with the source that reported it,' and data_as_of is null when unsupported. Provenance notes ('as accessed on', dated source citations) further characterize the data. Nothing contradicts the annotations.
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 essential call pattern is front-loaded in the first clause, and nearly every parenthetical earns its place ('business phones are public', 'Google listing fetch date when supported; otherwise null'). However, the return-field enumeration is a single dense run-on paragraph that would be significantly easier to parse as grouped bullets; its length is justified only because there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining the return value, and it does so exhaustively — field by field, covering ordering, provenance, null semantics, and the OPERATIONAL filtering rule. Remaining gaps: no behavior specified for not-found lookups, no explicit statement that slug takes precedence over name+city, and the exact inputs required for the name+city path (both together?) are only implied.
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%, and the description compensates for exactly the one uncovered parameter: includeClosed has only a type/default in the schema, while the description explains its effect on the OPERATIONAL filter. It also adds the slug semantics (tail of the ranked.ng/place URL) beyond the schema's example. For name and city it mostly restates the schema's pairing constraint, adding little new meaning.
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 by defining the resource precisely — 'One business listing from the production database, by slug... or by name + city' — and the field enumeration confirms a single-record lookup. It differentiates itself from plural/aggregate siblings (ranked_rankings, ranked_stats, ranked_hubs), but it never explicitly distinguishes itself from the closest sibling, ranked_find_business, so that contrast must be inferred rather than stated.
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 by the access pattern: an agent should call this when it already has a slug (the tail of a ranked.ng/place URL) or a name+city pair. The description also gives the conditional for includeClosed (non-OPERATIONAL places are excluded unless true). However, there is no explicit when-not-to-use guidance, no routing to ranked_find_business or ranked_rankings, and no statement about which lookup key takes precedence when both are supplied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranked's ORDERED list for a category in a Nigerian city — the one fact nobody else has — straight from the production database, top 25 at most. Category and city accept a slug ("hotels", "lagos") or a name ("Hotels", "Port Harcourt"). Served ONLY when the base page is published; otherwise { published: false, reason }. Each entry carries rank, url (https://ranked.ng/place/), Ranked's score and breakdown, Google rating/review count as provenance-carrying source data, an evidence-only verified tier, and data_as_of. The answer carries page_url, feed_url, last_published_at, methodology (https://ranked.ng/how-we-rank) and accessed_on = today. Paid placement never affects position. No product operated by Ranked is ever ranked.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | city slug or name, e.g. 'lagos' or 'Port Harcourt' | |
| limit | No | ||
| category | Yes | category slug or name, e.g. 'hotels' or 'Microfinance Banks' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive; the description adds substantial behavior beyond that: 'top 25 at most,' slug/name acceptance, a conditional published/unpublished failure shape, the exact entry fields, provenance details, methodology link, and explicit statements that paid placement never affects rank and Ranked products are never ranked.
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 core purpose and packed with operationally relevant details, including response structure, constraints, and integrity guarantees. It is somewhat long and includes rhetorical flourishes like 'the one fact nobody else has,' but for a tool with no output schema, the density is mostly justified.
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 carries the full burden of explaining response shape, and it does so thoroughly: per-entry fields, per-answer fields, failure behavior, URL pattern, data provenance, and methodology link. It leaves little ambiguity about what an agent will receive or what constraints apply.
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 descriptions already cover category and city with examples; the description reinforces slug-or-name acceptance and adds that results come 'straight from the production database' and are capped at 25, which clarifies limit's practical effect. It does not add significant meaning to the limit parameter beyond the schema's min/max/default, but it complements the schema well.
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 — Ranked's ordered list for a category in a Nigerian city — with a clear verb ('ranking'), and the category-plus-city scoping makes the tool's job unambiguous. It does not explicitly contrast itself with siblings like ranked_place or ranked_stats, so it stops short of full sibling differentiation.
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 when a category-and-city ranking is needed and adds the important precondition that it is served only when the base page is published. It does not explicitly state when to prefer this tool over siblings, nor does it name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Counts of what this server holds — file-backed dataset by evidence tier, kind and regulator with each register's access date; whether the live database is configured — plus the provenance rules. Use to explain provenance to a user.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'file-backed dataset' and 'whether the live database is configured,' giving some insight into internal checks. It does not contradict the readOnly/idempotent annotations, and it adds context beyond them. However, it does not elaborate on potential edge cases or side effects (which are minimal for a read-only tool).
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 long sentence with a dash and semicolon, creating a run-on structure that is difficult to parse. Phrases like 'file-backed dataset by evidence tier, kind and regulator with each register's access date' are cluttered and reduce clarity. It would be more concise and structured if broken into separate sentences or bullet points.
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 provides fragmented details (counts, configuration status, provenance rules) but does not clearly specify the output format or what exactly the tool returns. It lacks a straightforward explanation of the return value, making it incomplete for an agent to confidently use the tool without further inference.
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 has no parameters, so schema coverage is effectively 100%. Per the guidelines, this yields a baseline score of 3. No additional parameter details are necessary.
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 suggests a summary/statistics tool with 'Counts of what this server holds' and explicitly states 'Use to explain provenance to a user.' However, the verb is missing; it is unclear whether the tool returns counts, displays them, or performs something else. The phrasing is more of a content description than a clear action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a direct usage scenario: 'Use to explain provenance to a user.' This provides clear guidance on when to invoke this tool. It does not contrast with sibling tools, but the stated purpose is specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
compare_placesranked_by_regulatorranked_can_nigerian_payranked_check_licenceranked_compareranked_find_businessranked_hubsranked_placeranked_rankingsranked_statsSearch, verify & screen 1M+ African companies + their government contracts across 18 registries.
Live data from 27 official national company registries. Unmodified. For KYB and due diligence.
Official company and director data: search, profiles, filings, and name normalization.
Sanctions, PEP, watchlist, recall, business, and contract screening. Free tier, no auth required.
Add one secure layer between your agents and this server.
