AgentAvow Trust

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context about content (overview, verdict guidance, examples) but does not go beyond what annotations and the call-for-overview framing already convey.

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, no wasted words. The first sentence front-loads the content and value, the second gives a direct call-to-action. 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 tool with no parameters, clear read-only annotations, and a simple informational purpose, the description is complete. It tells the agent when to call it and what to expect, and there is no output schema requiring return-value documentation.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameters needing explanation. The description appropriately states 'No input', and the baseline for zero-parameter tools is 4.

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 states what the tool is for: an overview of AgentAvow, guidance on which tool to use for what, how to read verdicts, and example scans. It distinguishes itself from sibling tools by explicitly positioning it as the starting point and orientation tool.

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 'Call this for an overview or when getting started', which gives clear usage context. It also implies this tool helps with tool selection ('which tool to use for what'), effectively directing agents toward siblings when they need specific scans or lookups.

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 and destructiveHint=false, and the description reinforces this while adding 'Read-only, no auth' plus output fields such as is_safe, risk_level, score, and recommendation. This is useful context beyond the structured data. It does not discuss openWorldHint implications or error behavior, but the core behavioral profile is well covered.

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, all information-bearing: purpose, thresholds, return fields, and read-only/auth status. It is front-loaded with the core purpose and contains zero 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?

For a simple 2-parameter read-only check with no output schema, the description covers what it checks, thresholds, returned fields, and auth requirements. It does not describe unknown-entity errors or when to choose alternatives, but those gaps are minor since the schema already points to lookup_identity for resolving target_entity_id.

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 description maps each interaction_type enum value to a specific threshold (delegate 0.6, trade 0.5, collaborate 0.4, follow 0.1), which the schema's bare enum does not provide. This adds real semantic meaning for the primary parameter. The target_entity_id semantics are left to the schema, but the description partially compensates for the 50% coverage gap.

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 clear verb+resource: 'Check whether it is safe to interact with another agent by trust threshold.' It specifies interaction types and threshold values, which gives concrete meaning. It does not explicitly contrast with siblings like verify_trust or get_trust_badge, but the behavior is specific enough to be distinct.

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?

No guidance is given about when to prefer this tool over siblings such as verify_trust or get_trust_badge. The threshold list implies contexts for delegate/trade/collaborate/follow, but there are no explicit exclusions or alternative routing instructions. An agent must infer when this check is the right choice.

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 and destructiveHint=false; the description adds 'no auth' and the important dynamic behavior that 'the badge auto-updates as the score changes.' It also clarifies the output format (SVG plus Markdown/HTML), going beyond the structured hints.

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 purpose and immediately gives output and safety-relevant details (SVG, Markdown/HTML, auto-update, read-only, no auth).

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 with no output schema, the description is complete: it explains what the output contains (badge SVG, Markdown, HTML), that it auto-updates, and that no auth is needed. Nothing essential for invoking 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 entity_id parameter is already described as a UUID of a registered AgentAvow entity with resolution via lookup_identity. The description adds no new parameter-level meaning beyond what the schema provides, so the 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 uses a specific verb and resource: 'Get an embeddable AgentAvow trust badge (SVG) for an entity.' It also names concrete deliverables (Markdown and HTML), making the tool's purpose distinct from siblings like verify_trust or lookup_identity.

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 context is implied rather than explicit. The description states what the tool returns and mentions 'no auth,' and the schema parameter tells an agent to resolve the entity with lookup_identity. However, it does not explicitly say when to choose this tool over alternatives or 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.

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

Annotations already declare readOnlyHint and destructiveHint; description adds 'Read-only, no auth' which goes beyond annotations by confirming authentication requirements. It also discloses return fields, which is useful for caller expectations.

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, each with a distinct purpose: purpose, return values, usage context. No extraneous information, front-loaded with the primary action.

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 a single parameter, no output schema, and annotations covering safety, the description provides enough: it lists return fields, clarifies auth requirements, and gives usage context. An agent can call this tool correctly without needing more.

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 covers 100% of the parameter, describing acceptable input as a did:web:... or display name. The description's mention of 'by W3C DID or display name' aligns with the schema but adds no new semantics beyond what the schema already 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 (look up), resource (AgentAvow entity), and method (by W3C DID or display name), and lists the returned fields. Clearly distinguishes from siblings like verify_trust by focusing on identity resolution rather than trust assessment.

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?

Provides a clear usage context: 'resolve an identity before checking its trust.' This implies a sequencing relative to trust-checking tools like verify_trust, but it doesn't explicitly name alternatives 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.

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

Annotations already cover read-only and non-destructive behavior, so the description correctly avoids repeating those. It adds genuinely useful behavioral context: the tool calls the agentavow.com public API, and it returns a signed attestation. It does not mention caching or rate limits, but the parameter schema covers the caching behavior.

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 with no filler: the first states purpose and target, the second enumerates the return value, and the third discloses side-effect behavior. Every sentence earns its place and the key information is front-loaded.

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

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

With no output schema, the description compensates by enumerating the main outputs: trust score, verdict, findings, and signed attestation. It also explains why the scan is performed and that the operation is read-only, giving an agent enough information to select and invoke the tool correctly.

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

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

The schema describes both parameters with 100% coverage, so the baseline of 3 applies. The description reinforces that endpoint_url refers to the live MCP server and adds meaning about what is scanned, but it provides no additional parameter-level syntax or format details 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 names a specific verb and resource: scan a live MCP server's tool definitions for concrete risk categories (tool-poisoning, prompt-injection, invisible-unicode, manifest-execution). This distinguishes it from sibling scanners like scan_package and scan_repo, and the 'before your agent connects to it' phrase gives an explicit trigger context.

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 clearly states when to use the tool ('before your agent connects') and identifies the target as a live MCP server, which implies the boundary against package/repo scanners. It does not explicitly name alternatives or say when not to use it, so it stops short of full routing guidance.

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 and destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral context: it calls agentavow.com (an external remote dependency) and reports repo-vs-artifact drift. It repeats 'Read-only' from the annotation but also explains the return contents, so it goes beyond the structured fields.

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 tight sentences: the action and scope are front-loaded, the return value is summarized, and the remote/read-only nature is stated at the end. No sentence is wasted and no information is buried.

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

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

With no output schema, the description carries the full burden of explaining outputs, and it does so well: trust score range, verdict, findings with remediation, signed attestation, and drift reporting. It also covers the external call and read-only nature, making the tool's behavior sufficiently clear 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 five parameters, their aliases, and the force behavior. The description's ecosystem list reinforces the registry choices but does not add meaning beyond what the schema 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 ('Scan'), a specific resource ('a published package'), and enumerates the supported ecosystems (npm, PyPI, crates, Docker, Hugging Face). It clearly differentiates from sibling tools like scan_repo and scan_mcp_server by focusing on published packages rather than source repositories or MCP servers.

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 makes the intended use case clear: it is for published packages across named registries, not for source repos or MCP servers. It does not explicitly name sibling alternatives or say 'use scan_repo instead for source code,' but the context is strong enough for an agent to route correctly.

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 and destructiveHint=false, and the description adds that it is read-only and requires no account while making an external call to agentavow.com. It also discloses the signed, offline-verifiable nature of the result, which goes beyond the schema and annotations.

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

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

Three short sentences carry all the essential information, with the main result list front-loaded and no redundant filler.

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

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

Given no output schema, the description enumerates the return payload (score, verdict, findings, fix locations, attestation) and the access/network expectations. All required parameters are documented, and the tool is simple enough that no critical detail 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%, so the schema documents all three parameters. The description adds little beyond saying the repo is public; the cache behavior and owner/repo options are already described in 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 names a specific action ('Scan a public GitHub repository') and resource type, and it lists the concrete outputs (trust score, verdict, findings, attestation) and the external service used. This makes it easy to distinguish from sibling tools like scan_mcp_server and scan_package.

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 establishes that this is for public GitHub repositories and states the access constraints ('Read-only, no account'), but it never explicitly says when to choose scan_repo over check_interaction_safety or verify_trust. Usage context is implied rather than stated.

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 and destructiveHint=false, covering safety. The description adds 'no auth' and a usage hint, but it does not disclose error handling or behavior for unknown entities (the schema covers that). With annotations present, the description contributes only modest additional behavioral context.

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 that front-load the purpose and immediately state return values and usage context. No unnecessary words 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?

For a simple two-parameter read-only tool with annotations and a full schema, the description covers the essential behavioral details: return fields, read-only status, auth requirements, and a usage recommendation. Nothing critical is missing for an agent to call 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 description coverage is 100%, so both parameters (entity_id and min_trust) are already fully documented. The description does not add any parameter-specific meaning beyond what the schema provides, so it meets the baseline of 3.

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 states the tool's action ('verify') and resource ('trust score'), lists the returned fields (trust_score, trust_score_pct, trust_tier, threshold), and provides a usage context that distinguishes it from general lookups. While it doesn't explicitly contrast with get_trust_badge, the purpose is unambiguous and specific.

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 when-to-use directive: 'Use before interacting with an unknown agent.' It does not mention alternatives or exclusions, but the context is clear enough for an agent to decide when this tool is appropriate.

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