Trusgent MCP

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior, so the description does not need to restate those. It adds that this is a preflight capacity check and provides the HTTP GET equivalent, but it leaves the exact response shape and how capacity is represented to inference.

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 compact sentences front-load the purpose and workflow position, then add the HTTP equivalent. There is no filler or redundant restatement of the tool name.

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

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

For a low-complexity check with rich annotations and full parameter documentation, the description is largely sufficient. It could be more explicit about what the returned availability looks like, but the name and 'remaining reservation capacity' phrasing provide enough context 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 input schema already documents all three parameters with their formats, giving 100% schema coverage. The description's HTTP query string repeats those formats but does not add 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 action—checking remaining reservation capacity for a business facade slot—and explicitly positions it as a preflight step before create_reservation. This clearly distinguishes it from sibling tools like get_business_facade or create_reservation.

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 explicitly says to use this tool 'before create_reservation', giving clear contextual placement in the workflow. It does not spell out when not to use it, but the intended use case is unambiguous given the sibling tool 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?

Adds real side-effect disclosure beyond the annotations: it stores the inquiry and emails a claim CTA when a contact candidate exists, and describes a conditional nextStep return. Annotations only give openWorld/non-idempotent hints, and the description usefully explains what the write actually does. It stops short of warning that repeat calls are non-idempotent and may create duplicate inquiries.

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?

Four short sentences with the core action front-loaded, then branch behavior, then a guardrail. Dense and mostly waste-free, though 'claim CTA' is jargon that could be spelled out.

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 non-read-only, open-world write with 7 params and no output schema, it covers side effects, return branching, and a data-integrity guardrail. Remaining gaps are the unclaimed-case response shape and duplicate-creation risk given non-idempotency.

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 each of the 7 parameters is already documented in the schema. The description adds minor context about registryId identifying an official Business Agent and implicitly warns against fabricating requesterPhone values, but nothing about formats or constraints beyond that.

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

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

States a specific verb+resource ('Send a service intent to an official Business Agent') and ties it to the registryId key. It also splits the two behavioral branches (unclaimed vs already claimed) and explicitly names the sibling tools get_agent / get_business_facade for the claimed case, so an agent can place it among its 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?

Gives clear conditional routing: use this for unclaimed rows, and follow nextStep to get_agent / get_business_facade when already claimed. It also adds a concrete do-not ('Do not invent phone numbers'), but it does not differentiate from other creation siblings like create_reservation or create_order.

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?

Adds meaningful context beyond annotations: the order is initially PENDING and kitchen confirmation happens in Dashboard, and menu item names must match facade.menu. Annotations already communicate mutation and non-idempotency; the description enriches that with operational detail.

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?

Compact and front-loaded, with the main action in the first sentence. The HTTP-equivalent clause is useful but slightly redundant; otherwise each sentence earns its place.

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

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

Given complete schema coverage and the annotations, the description supplies the key behavioral facts an agent needs: pending status, kitchen confirmation, and restaurant-facade-only eligibility. It does not describe the response shape, but there is no output schema and the omission is not critical 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the items naming constraint but does not add substantial new parameter-specific meaning beyond what the schema 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?

States a specific verb (Submit) and resource (order) with a clear source ('published restaurant facade menu'). The 'Restaurant facades only' qualifier and 'order' resource distinguish it from siblings like create_reservation.

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?

Gives clear usage context: submitting dine-in/takeaway orders against a published restaurant facade, with an explicit exclusion ('Restaurant facades only'). It does not explicitly name alternative tools or when-not conditions beyond facade type, so it falls just short of a 5.

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

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

The annotations already signal a non-read-only mutation that is not idempotent, and the description adds valuable behavioral context: the reservation starts as PENDING, the merchant confirms in Dashboard, and it is not an instant booking. This goes beyond the structured annotations without contradicting them.

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 short, front-loaded, and every sentence earns its place: purpose, outcome state, non-guarantee, and HTTP equivalent. No filler or repetition.

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

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

The description explains purpose and behavioral outcome, but with no output schema and 11 parameters it omits the response shape and any preconditions, such as checking availability before reserving. It is adequate but not fully complete for a create-style operation.

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 all 11 parameters are already documented in the input schema. The description adds no new parameter-level meaning; the HTTP path with {handle} is essentially a restatement of the handle parameter.

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

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

The description clearly identifies the operation: submit a booking or appointment request for a published business facade, creating a PENDING reservation. It does not explicitly contrast itself with sibling tools like create_order, so sibling differentiation is only implicit.

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 intended usage is implied: use this tool to request a reservation or appointment. However, there is no explicit guidance about when to prefer this over check_availability or create_order, and no clear when-not-to-use criteria beyond 'not a guaranteed instant booking'.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description adds value by disclosing the return payload — structured profile fields, trustScore, verification, and canonical URLs — which matters because there is no output schema. It stops short of noting error behavior for unknown IDs.

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, zero waste. The lookup scope is front-loaded and the return contents follow immediately, so an agent gets purpose and payload in one pass.

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

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

With no output schema, the description usefully enumerates what comes back (profile fields, trustScore, verification, canonical URLs). It is nearly complete for a single-fetch tool but does not address lookup failure or how it relates to sibling single-agent tools like get_merged_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% for the single agentId parameter, giving a baseline of 3. The description goes slightly beyond by anchoring the ID's provenance ('same ID used in /t/{id} and /b/{id}'), clarifying which identifier form is expected, though the schema example already helps.

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

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

States a specific verb and resource ('Fetch one full Agent Card by public agentId') and scopes the lookup to a single agent. However, it does not explicitly distinguish itself from close siblings like get_merged_profile or verify_agent, so an agent still has to infer which single-agent tool it wants.

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 'by public agentId' — use this when you have a known ID and want the full card. There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as search_agents for discovery or verify_agent for trust checks.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds value by clarifying that the data reflects what the merchant 'currently publishes' and warns against inventing menu items, which reinforces the open-world nature of the data. It also clarifies that the handle is the same public ID/handle as /b/{id}.

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 two sentences with no filler. It front-loads the core fetch operation and resource definition, then supplies usage context and a critical anti-hallucination instruction, all in a compact form.

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

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

For a one-parameter, read-only fetch tool with strong annotations, the description is complete: it names the return categories, identifies the handle source, states the intended use case, and warns against fabrication. No critical information is missing for an agent to invoke it 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 already describes the single 'handle' parameter with 100% coverage, but the description adds meaningful context by noting it is the same public ID/handle used in /b/{id}. This helps an agent understand where to source the value, which goes beyond the schema's terse 'Agent Handle / facade handle' label.

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 ('Fetch') and a clearly defined resource ('published business facade') with concrete contents listed (menu/services, hours, booking capabilities). It also ties the identifier to the public /b/{id} route, making the tool's role distinct from sibling tools like get_agent or get_merged_profile.

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 explicitly states when to use the tool: 'Use for customer-facing answers about what the merchant currently publishes.' It adds a strong negative instruction ('do not invent menu items'), but it does not explicitly name alternative tools or state when not to use this one.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds valuable context beyond that by enumerating the returned sections (businessAgent, dossierLayers, citationPolicy, trustBreakdown, recommendedUse) and explaining that unclaimed official rows remain callable, which is 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?

Two tight sentences with no filler, and the core identity as the preferred merged read is front-loaded. The return-field enumeration is dense jargon but each term maps to a real output section, so it earns its place.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so by naming the key sections and the claimStatus/capabilities subfields. The unclaimed-row behavior and create_inquiry escalation round out the important edge case, leaving only minor gaps such as error behavior or locale effects.

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% and both parameters are documented there: registryId with an example handle and locale with allowed values. The description mentions neither parameter, so it adds no meaning beyond the schema and the baseline of 3 applies.

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

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

The description states a specific operation ('Preferred HK Business Agent read') and precisely defines the resource as official registry fields merged with Agent Card data and cited third-party enrichment. It distinguishes itself conceptually from raw-source siblings like get_registry and get_agent, though it does not name those alternatives explicitly.

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

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

It signals that this is the preferred read and routes the agent to create_inquiry when a row is unclaimed, which is clear guidance for that edge case. It stops short of explicitly stating when to choose this over get_registry or get_agent, so an agent must infer the preference from 'Preferred'.

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

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

Annotations already cover the safe read-only, idempotent profile, so the description does not need to repeat that. It adds useful behavioral context by disclosing that the response includes methodology, asOf, paidPlacement=false, and recommendedUse, which tells the agent what kind of structured data to expect.

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 four short sentences with no filler. The primary purpose is front-loaded, and each sentence earns its place by adding either usage guidance, alternative avoidance, return-field context, or a parameter rule.

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

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

For a simple read-only lookup tool with three well-documented parameters and strong annotations, the description is complete. It names the key output fields, states the required parameter behavior for market boards, and gives the intended use case, so an agent has everything needed to invoke it 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?

Schema coverage is 100%, with each parameter already described in the input schema. The description repeats the tenureMonths guidance for market boards without adding meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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 ('Fetch') and resource ('one ranking board') and clarifies that it returns 'structured items for citation,' which distinguishes it from the sibling list_rankings tool. It also preempts an alternative approach (scraping HTML), making the tool's role unmistakable.

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 states when to use the tool ('for citation') and explicitly recommends it over scraping HTML. It also gives conditional guidance for market boards via tenureMonths. It does not explicitly mention when to use list_rankings or other siblings, but the context is otherwise 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the description does not need to re-state safety. It adds useful behavioral context by specifying that the response contains official fields plus provenance and verify links, helping the agent anticipate the result despite no output schema.

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 with no filler. The core fetch behavior and identifier format are front-loaded, and the routing guidance to the sibling tool comes in a compact second sentence.

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 single-parameter read-only tool, the description covers what it returns, how to identify the record, and when to choose the sibling tool instead. Annotations handle safety characteristics, and there is no output schema requirement being neglected.

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 already fully documents the sole parameter with an example, including coverage of 100%. The description echoes registryId as the lookup key but adds little semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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 ('Fetch one official Hong Kong registry record by registryId') and names the distinctive output ('official fields plus provenance and verify links'). It also differentiates from get_merged_profile by mentioning what this tool does not cover.

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 explicitly instructs to prefer get_merged_profile when claim status, enrichment, or recommendedUse citation hints are needed, which tells the agent when not to use this tool and what alternative to select.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns a catalog with htmlUrl and jsonUrl per board, and explains the sorting logic for each board type. This goes beyond the annotations without contradicting them.

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 sentences with no filler. The core purpose is front-loaded, the board-type distinction is explained in the second sentence, and the return format is stated in the third. Every sentence earns its place.

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

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

For a read-only list tool with no required parameters and full schema coverage, the description is nearly complete. It states the return format (catalog with htmlUrl + jsonUrl) and the sorting semantics. It does not explain what the track filter values map to explicitly, but the board-type explanation makes this inferable.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the distinction between 'trust' and 'market' tracks implicitly via the board types, but does not explicitly map the track values to board categories. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 ('List') and resource ('Trusgent ranking boards'), and immediately distinguishes the two board types (merchant vs. rate boards) with concrete examples. It also names the sibling tool 'get_ranking' implicitly by describing the catalog-level return, making it clear this is the list-level counterpart.

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 returns and the two board categories, which gives clear context for when to use it. It does not explicitly name alternatives or exclusions, but the sibling list (get_ranking, search_registry) and the catalog-level wording make the intended use reasonably 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?

Annotations already declare read-only, idempotent, non-destructive behavior; the description adds useful behavioral context by disclosing keyword + semantic (embedding) retrieval and by enumerating the returned AgentCard fields. This goes beyond the structured metadata.

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?

Five sentences, each contributing a distinct fact: resource, retrieval method, return shape, recommendation preference, and usage exclusion. The core action is front-loaded and no sentence is redundant.

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 read-only search tool with no required parameters, the description covers what it searches, how it searches, what it returns, and how to use the results. The absence of an output schema is mitigated by listing the returned fields.

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 adds value by explaining that q is used for keyword + semantic embedding retrieval and that results are AgentCard objects. It does not add per-parameter detail for sort, type, country, etc., but the schema already covers those.

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

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

The description names a specific verb and resource: searching the Trusgent Trust Layer directory for people and businesses with public Agent Cards, and it clarifies the retrieval mechanism. However, it does not explicitly contrast itself with sibling search_registry, leaving some potential overlap for an agent to infer.

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 tells the agent exactly when to invoke this tool ('Use before recommending any agent to an end user') and what not to use it for ('Do not treat this as intent/demand matching — that is a separate flow'). It also instructs a preference for verified agents when recommending, which shapes result usage.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive open-world lookup. The description adds useful behavioral context beyond that: each hit carries a businessAgent facet with claimStatus, capabilities, and inquiryUrl, and unclaimed rows remain callable. It does not describe result ordering or pagination behavior, so it is not fully 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?

Three dense sentences, front-loaded with what is searched and how broad it is. Every sentence adds value: searchable fields, source enumeration, return facet, and the follow-up tool. There is no redundant restatement of annotations or 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?

For a read-only search tool with no output schema, the description is largely complete: it explains what can be searched, what a hit contains, and how to proceed for citation-safe detail. It leaves minor gaps around result ordering and whether the country parameter narrows beyond Hong Kong, but nothing essential to calling the tool correctly is missing.

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 earns extra credit by clarifying that the free-text q parameter matches name, address, licence number, or registryId, and by giving concrete source values (FEHD_RESTAURANT, CR_COMPANY, EHEALTH_HCP) that the schema only calls an optional enum.

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 gives a specific verb (search) and resource (Hong Kong official Business Agents) and quantifies scope (~60k+ registry rows). It names the searchable fields and source dimension clearly. It does not explicitly distinguish itself from sibling search_agents or get_registry, which keeps it from a 5.

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

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

It provides clear usage context: unclaimed rows are still valid for lookup and create_inquiry, and the agent should follow up with get_merged_profile for citation-safe detail. It lacks an explicit statement of when to prefer this over search_agents or get_registry, so it stops short of full alternative 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely non-structured context: that it is a lightweight lookup, that trustScore is a published formula composed of identity verification, official records, completeness and source consistency, and that reviews are auxiliary only — useful for interpreting the result.

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 sentences, front-loaded with the core capability and the return fields, followed by usage routing. The trust-score formula clause is slightly dense but earns its place by explaining the tool's headline output.

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?

There is no output schema, so the description must describe the return values, and it does enumerate them (existence, public status, verification level, trustScore) plus how the score is derived. For a single-parameter read-only lookup, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% with a single well-documented agentId parameter, so the schema carries the burden. The description adds no syntax, format, or scoping detail about the identifier beyond what the schema already states; baseline 3 applies.

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

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

States a specific verb (verify/lookup) and resource (AgentID) and enumerates exactly what is returned: existence, public status, verification level, and trustScore. It implicitly contrasts with search results, but never names the closest sibling get_agent, so the differentiation from a plain agent-fetch tool is left to inference.

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

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

"Prefer this before citing or recommending an Agent Card from search results" gives a concrete when-to-use trigger tied to a workflow (citing/recommending). It offers no when-not guidance or named alternative, so it stops short of full routing instructions.

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