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 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 establish readOnly, idempotent, and non-destructive behavior, and the description aligns with them. It adds useful context beyond annotations by naming the return contents (structured profile fields, trustScore, verification, and canonical URLs), which helps the agent know what to expect. It does not describe error/pagination behavior, but that is less critical for a simple single-ID fetch.

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 carry the entire definition with no filler. The fetching purpose is front-loaded, and the return summary follows immediately, making the description scannable and 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 one-parameter, read-only tool with no output schema, the description is complete enough: it tells exactly what identifier to provide and gives a clear idea of the response shape (profile fields, trustScore, verification, canonical URLs). The annotations cover safety, so nothing critical 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?

The input schema already documents trusgentId fully, including the type and example (TG-S-839201), so the baseline is 3. The description contributes only a small additional cue by noting the same ID is used in /t/{id} and /b/{id}, but this does not add material new format, validation, or supply details.

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

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

The description opens with a concrete verb ('Fetch') and a specific resource ('one full Agent Card'), then specifies the identifying scope ('by public trusgentId') and cross-references the canonical URL endpoints. This makes it easy to distinguish from sibling tools like search_agents, get_registry, or verify_agent, even without naming them.

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 wording gives a clear trigger: use this when you need a single complete Agent Card by its public ID. It does not explicitly list sibling alternatives or when-not-to-use cases, but the scope is clear enough that an agent can select it confidently for one-card fetch operations.

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/non-destructive behavior, and the description adds provenance context: official data merged with claimed Agent Card data and cited third-party enrichment, plus a warning that reviews are auxiliary and not scraped from the open web. It also says the output includes citationPolicy and trustBreakdown, which is behavioral info beyond safety flags.

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 dense sentences front-load the core message ('Preferred HK registry read') and each clause adds value—data provenance, output fields, safety purpose, and a review caveat. No filler or repetition of schema/annotations.

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 tool with only one required parameter and rich annotations, the description covers what the merged profile contains, why it is trustworthy, and a data-source caveat. It is complete enough to select and call correctly alongside the listed siblings.

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 fully documents registryId as a public handle and locale as a language code. The description doesn't add parameter-level meaning beyond implying the HK registry context, so a baseline 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 composite-read purpose: official HK registry fields merged with claimed Agent Card data and cited third-party enrichment, and names key output fields (dossierLayers, citationPolicy, trustBreakdown, recommendedUse). The phrase 'Preferred HK registry read' signals how it relates to sibling registry tools, so an agent can distinguish it from get_agent/get_registry without opening schemas.

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 marks the tool as the 'Preferred HK registry read' and explains it exists to tell agents what is safe to cite, giving clear usage context. It does not explicitly list when-not-to-use or name alternatives like get_agent/get_registry, but the 'Preferred' flag and the merge of data sources imply the 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?

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 cover read-only, non-destructive, open-world, and idempotent behavior. The description adds useful operational details beyond that: it returns 'lightweight rows' containing profileUrl and mergedUrl, and it recommends a separate tool for citation-safe detail. This gives the agent expectations about result shape and the need for follow-up.

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 three brief sentences with no filler. The main purpose and search keys are front-loaded, the optional source filter is given in one clause, and the output/next-step guidance is concise. Every sentence carries operational value.

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 search tool with no output schema, the description adequately hints at return rows and the proper follow-up tool for detailed data. It does not exhaustively list all result fields or edge cases, but combined with annotations and a fully self-described parameter schema, it gives sufficient 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?

All four parameters are already described in the schema, so the baseline is 3. The description adds meaningful detail on q (name, address, licence number, registryId) and gives examples of the source enum, but it does not go deeper on limit or country semantics. This is good but not exceptional compensation over 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 ('Search'), a clear resource ('Hong Kong official registry records'), and the searchable keys (name, address, licence number, registryId). It is distinct from the sibling tools in function, though it does not explicitly name and differentiate itself from get_registry or search_agents.

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 for when to call the tool: when you need to search official Hong Kong registries by common identifiers, with optional source filtering. It also routes a follow-up use case ('follow up with get_merged_profile for citation-safe detail'). However, it does not explicitly state when to prefer get_registry or search_agents instead.

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 read-only/idempotent behavior, so the bar is lower. The description adds valuable context beyond annotations by explaining the trustScore is a published formula and that reviews are auxiliary only, which helps the agent interpret results correctly.

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 first sentence front-loads the lookup purpose and output fields, and the second provides actionable usage guidance. Every clause earns its place.

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

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

For a one-parameter, read-only, idempotent lookup with rich annotations, this description is complete. It defines what the tool checks, what trustScore means, and when to prefer it. No output schema is required for this level of complexity.

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 single parameter trusgentId is fully described in the schema as 'Public AgentID to verify,' so the description adds no additional format or constraint information. Schema coverage is 100%, making the baseline 3 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 operation ('Lightweight verification lookup') witha concrete resource (AgentID) and the exact facts returned (existence, public status, verification level/trustScore). This clearlydifferentiates it from sibling retrieval and search tools such as get_agent and search_agents.

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 an explicit usage rule: 'Prefer this before citing or recommending an Agent Card from search results.' This tells the agent when to call it, but it does not explicitly name alternative tools or state when not to use it.

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