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 provide readOnlyHint, openWorldHint, and idempotentHint, lowering the bar. The description adds useful behavioral context by clarifying this reads current public data and that it corresponds to /b/{id}, reinforcing that this is not a write or internal operation. The 'do not invent' rule further signals that the agent should treat this as source-of-truth for publication visibility.

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 concise sentences achieve all the necessary functions: define the resource, list what it contains, give usage context, and add a critical hallucination warning. There is zero filler, and 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?

Given there is no output schema, the description does appropriate work by naming the core data types returned (menu/services, hours, booking capabilities). One could hope for more return-value structure, but for a single-required-parameter read-only operation with full annotation coverage, this is sufficient for reliable 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?

With 100% schema coverage, the baseline is 3, but the description strengthens meaning by telling the agent that 'handle' refers to the same public ID/handle used in /b/{id} paths. This aligns the parameter with a recognizable API pattern and confirms it is a public-facing identifier, not an internal database key.

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 verb 'Fetch' combined with the resource 'published business facade' is specific, and the parenthetical expands what constitutes the facade: menu/services, hours, booking capabilities. It also ties the item to the public URL pattern /b/{id}, defining the resource precisely. An agent can confidently know what this tool fetches without opening the schema.

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

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

The description explicitly says 'Use for customer-facing answers about what the merchant currently publishes,' giving a clear when-to-use context. It additionally instructs not to invent menu items, an important guardrail. It doesn't mention alternative tools, but the intended context is clear enough to select it appropriately.

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 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?

The annotations already declare the tool as read-only, idempotent, and non-destructive, so the bar for additional disclosure is lower. The description adds useful behavioral context: it searches only public Agent Cards and returns AgentCard objects with specific fields. This goes beyond the annotations by clarifying the result shape and directory scope.

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. The first sentence front-loads the core purpose and return type, and the second sentence provides practical usage guidance. 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?

Given the lack of an output schema, the description helpfully summarizes the returned AgentCard fields. It also provides a clear usage scenario, which is especially useful because annotations are sparse. The only minor gap is that pagination or result-size behavior is not mentioned, but this is not critical for a simple directory search 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 input schema has 100% description coverage, with clear descriptions for all 6 parameters, so the description is not required to re-explain them. The narrative description adds minimal parameter-level meaning, mostly reinforcing the search intent. Baseline 3 is appropriate because the schema already carries the full parameter 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 uses a specific action verb ('Search') and a clear resource ('Trusgent Trust Layer directory for people and businesses with public Agent Cards'). It also describes the return shape, making the tool's purpose concrete. However, it does not explicitly distinguish itself from the sibling tool search_registry, so the differentiation is slightly incomplete.

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 clear usage context: 'Use before recommending any agent to an end user.' This tells an agent when the tool is relevant. It does not name alternatives or state when not to use it, but the use context is sufficiently concrete.

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.