AgentTrust — Pre-Invocation AI Agent Trust & Reliability Checks

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

Beyond the readOnly/idempotent annotations, the description discloses the decision vocabulary, the full set of returned fields, that it never contacts the endpoint, that reachability is not safety, and that no API key is needed. These are real behavioral facts an agent needs before calling.

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?

It leads with the core decision and is front-loaded with the most important facts. It's dense, and enumerating all return fields slightly exceeds what's needed given the output schema, but nothing is wasteful.

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 assessment tool with annotations and an output schema, the description covers purpose, the decision model, safety caveats, and data provenance. An agent has everything required to call it and interpret the result.

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 is fully documented in the schema (100% coverage), including the exact-URL and never-contacted semantics. The description adds little about the parameter beyond what the schema already states, so 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?

The description states a specific action and resource: an immediate use-or-avoid decision about an AI agent or MCP server endpoint, framed for an agent deciding whether to call it. It clearly differs from CRUD-style siblings like get_agent and list_agents, though it never names them 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?

The intended moment of use is explicit: 'for an agent deciding whether to call it.' No exclusions or named alternatives (e.g., check_agent_trust) are given, so the agent must infer which sibling to prefer.

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 destructiveHint=false, yet the description still adds real behavioral context: no API key or account required, the endpointUrl is never contacted, only AgentTrust's own observation history is read, and an unregistered URL degrades to { matched: false } rather than an error. That no-auth, no-network, no-error contract is exactly what an agent needs to decide whether calling this is safe and cheap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then the cost/safety guarantees, then the return shape, then the edge case — a sensible ordering. Slightly repetitive: 'requires no API key' and 'does NOT contact endpointUrl itself' both appear to pre-empt the same worry about side effects, costing a little tightness.

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?

An output schema exists so return values need not be spelled out, and the description still summarizes the payload (status, ownership verification, reliability score, trustDecision) plus the not-found behavior. With annotations covering safety and the only edge case ({ matched: false }) called out, nothing material is left for the caller to guess.

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 the parameter is single and well documented, so the baseline is 3. The description adds the 'exact invocation URL' requirement — i.e. matching is exact rather than fuzzy — plus the reassurance that the URL is used only for lookup, both of which are semantic value beyond the schema text.

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 ('Pre-invocation trust check for an unknown AI agent or MCP server endpoint') and scopes it to one-shot, credential-free lookups, which implicitly separates it from the authenticated get_agent/get_agent_health siblings. It never names a sibling directly, so an agent must infer the boundary from the 'unknown agent / pre-invocation' framing rather than being told outright.

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?

'Pre-invocation' gives a clear triggering context — call this before invoking an agent you don't already trust, without an API key. There is no explicit when-not guidance (e.g. 'use get_agent instead when you already have a registered agent ID') and no alternatives are named, which is the only gap.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the returned payload shape (Agent Card, reliability score, trustDecision with recommended/confidence/reasons), which is useful context even though an output schema exists.

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?

A single dense sentence that front-loads the operation and then enumerates the response contents. Every clause serves a purpose, though the return-value enumeration is somewhat heavy for a one-parameter read tool.

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 single-parameter read tool with full schema coverage, annotations, and an output schema, the definition is essentially complete. It arguably over-explains return values that the output schema already carries, but 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%, and the slug parameter is fully documented in the schema as the URL slug from a profile or list_agents result. The description only echoes that lookup is by slug, adding no syntax or format detail beyond the schema, so the 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 (Get) and resource (one AgentTrust agent) qualified by slug, plus what the response contains. It distinguishes itself reasonably from list_agents and get_agent_health by being the single-agent profile fetch, but it never names a sibling 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?

The phrase 'for deciding whether to invoke it' implies the decision-making context, but there is no explicit when-to-use vs when-to-use-alternatives guidance, and check_agent_trust is never mentioned as the likely alternative 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description goes beyond them by explaining how the status is derived — heartbeat freshness for push-mode agents, latest pull check otherwise — and that the result is an 'effective' (computed) status rather than a raw reading. It still omits behavior for unknown slugs or agents that have never reported.

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?

One sentence, front-loaded with the action and resource, with the derivation rule attached as a qualifier rather than padding. Nothing here is wasted.

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 an output schema present, the description needn't explain return fields; it only has to identify the resource and the one input, which it does. The push/pull derivation note supplies the extra context a caller needs for a health tool, so nothing material 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?

There is a single parameter at 100% schema description coverage, so the schema already documents the slug, its source and its length bounds. The description adds no further meaning about the parameter, which matches the baseline of 3 when the schema does the heavy lifting.

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 ('Get one agent's current effective health status and monitoring detail') and clarifies that the value is computed rather than stored. It does not explicitly distinguish itself from the sibling get_agent, but the 'health status' framing is distinct enough that an agent can pick it out of the sibling list.

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 — reach for this when you need an agent's health — and the sentence about push-mode vs pull-mode derivation hints at which internal data source feeds the result. There is no explicit when-to-use/when-not statement or named alternative (e.g. 'for raw config use get_agent'), so guidance stays at the implied level.

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 bar is lower. The description adds valuable context beyond annotations: it requires an API key, explains the trust-check response contents (reliability score, ownership verification, trustDecision), and routes anonymous checks to a sibling. It does not cover rate limits or pagination details, so it falls short of a perfect 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and compact: it opens with the core purpose, then explains the two modes in three efficient sentences. Every sentence carries useful selection or behavioral information, with no filler or redundancy.

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

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

Given the tool's complexity, rich annotations, complete parameter schema, and existing output schema, the description is complete enough. It covers purpose, both invocation modes, authentication, return highlights, and the relevant sibling alternative without needing to duplicate schema or output details.

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 limit, cursor, and endpointUrl in detail, including exact matching behavior and empty-list handling. The description reinforces the intent of endpointUrl for trust checking, but adds little semantic detail beyond what the schema already provides. 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 verb and resource ('Discover AgentTrust agents' and 'returns the plain paginated listing'), and explicitly distinguishes the tool from sibling check_agent_trust by naming that alternative for anonymous checks. An agent can tell exactly what this tool does and how its two modes differ.

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

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

It gives explicit when-to-use guidance: pass endpointUrl to check trust status before deciding whether to invoke an agent, omit it for a plain public listing, and use check_agent_trust for an anonymous pre-invocation check. Both the primary condition and the alternative route are clearly specified.

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 this is a non-read, non-idempotent, non-destructive write. The description adds genuinely new behavioral context beyond that: the server assigns the timestamp and client-supplied time is rejected, which tells the agent what it cannot control. It stops short of explaining the idempotentHint=false consequence (repeated calls recording separate heartbeats).

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, zero filler. The core action and its liveness effect are front-loaded, with the timestamp constraint as a supporting clause.

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

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

For a one-parameter write with an output schema and full annotation coverage, the description supplies the essentials: ownership scope, liveness semantics, and server-side timestamp authority. Only idempotency behavior and any rate-limit expectations are left unstated, which is a minor gap.

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

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

Schema coverage is 100% and the single slug parameter is fully documented in the schema, including its source (public profile or list_agents). The description adds only the ownership constraint, so the schema does the heavy lifting and the 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 and resource ('Record a push-style heartbeat for an agent you own') and clarifies the effect ('marking it alive right now'). This functionally separates it from read-oriented siblings like get_agent_health or check_agent_trust, though no sibling is named 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?

The phrase 'for an agent you own' implies an ownership prerequisite, which is useful context. However, there is no explicit guidance on when to call this versus get_agent_health or how frequently heartbeats should be sent, leaving usage to inference.

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