AgentPort Discovery

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

Annotations already convey read-only, idempotent, non-destructive behavior, so the description adds useful context beyond that: the workflow stage, the stable-slug requirement, and the fact that the tool exposes exact published capability/action keys. This effectively explains what the call will return without contradicting the 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?

Two sentences with no filler. The inspection-step framing is front-loaded, the core action is stated immediately, and the routing guidance to capability.resolve is placed at the end without 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 absence of an output schema, the description does a good job indicating what can be learned from the result: exact published capability/action keys. Combined with clear workflow positioning and sibling differentiation, little is left ambiguous for such a simple single-parameter read-only 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?

Schema description coverage is 0%, but the description supplies important meaning for the single parameter: slug is a stable AgentPort registry slug for a discovered business. This tells the agent to use a canonical identifier from a prior discovery step rather than arbitrary text, complementing the schema's format pattern.

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 resolves and inspects a business by its stable AgentPort registry slug, with a specific purpose: to view exact published capability/action keys. It also distinguishes itself from capability.resolve by explicitly noting this is not final resolution for actionable requests.

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 frames the tool as an 'inspection step' and tells the agent to call capability.resolve after canonical keys are known for actionable requests. It also implicitly scopes usage to already-discovered businesses, indicating business.search would be the discovery path.

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, idempotent, open-world, and non-destructive behavior. The description adds a scope constraint (only real, published AgentPorts) and exact capability filtering, but does not describe result shape or pagination, so value beyond annotations is moderate.

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 front-loaded sentence with no filler. The action, scope, and search dimensions are all stated efficiently, and every phrase carries meaning.

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 nine optional parameters and no output schema, the description is adequate but not complete. It gives the search concept but omits return-format expectations and the mechanics of combining location filters, so an agent would need schema details or examples for full confidence.

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 only 33% schema description coverage, the description partially compensates by grouping parameters into 'natural-language need,' 'location,' and 'capability keys.' However, it does not explain individual location options (city, region, lat/lon, radius, country) or the limit parameter, leaving a meaningful semantic 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 names a specific action ('Find'), a concrete resource ('real businesses with published AgentPorts'), and the search dimensions: natural-language need, location, and capability keys. This clearly distinguishes it from business.get (retrieval by ID) and capability.resolve (capability lookup).

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 a clear use context: discovery of businesses by need, place, and capability filters. It does not explicitly state when to prefer business.get or capability.resolve, so it stops short of full alternatives 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?

The description adds behavioral context beyond the annotations: it explicitly states 'without executing the selected action', reinforcing readOnlyHint, and explains the 'ranked' output and 'never invent keys' constraint. No contradictions with the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint 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?

The description is four sentences, each contributing a distinct point (purpose, usage context, key constraint, fallback). It is information-dense without being bloated, though it could be slightly streamlined without losing meaning.

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 complex tool with nested objects and no output schema, the description covers the core decision framework: when to call, what not to do (never invent keys), and how to discover valid keys. However, it omits semantics for several parameters like 'constraints' and 'preferences', leaving some ambiguity for correct full 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 description meaningfully clarifies the four array parameters by requiring 'exact canonical AgentPort keys' and naming business.search/business.get for discovery. However, with schema description coverage at 36%, it does not explain the required 'intent' parameter, nor the 'constraints', 'preferences', 'desiredOutcome', or 'executionRequired' fields, which remain ambiguous.

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 ('resolve') and resource ('structured user goal to ranked machine-capable resources and provider-owned execution paths'), and is explicitly positioned as the 'final discovery step' distinct from business.search/business.get. This makes it clear what the tool does and how it differs from its siblings.

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

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

The description explicitly says 'Use this after business.search/business.get whenever the user asks whether a provider can expose a machine-capable action or execution path' and directs users to 'If exact keys are unknown, use business.search and business.get first.' This provides clear when-to-use and when-not-to-use instructions with named alternatives.

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