Flipvo: contractor licenses, business entities, drive times, airports

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

The annotations already mark the tool as readOnly and openWorld, but the description adds valuable context: the $0.02 per call cost, the payment method (x402/MPP), and the ranking by real road drive time. It also clarifies that only scheduled-service airports are considered. No contradictions with 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 two sentences: the first front-loads cost and payment details, the second states the core functionality. It is concise and structured well, with no redundant phrasing, though the payment info could arguably be moved to a separate field.

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 tool has an output schema, so return values need no explanation. The description covers the main purpose, cost, payment, and ranking behavior. It doesn't mention error handling or rate limits, but for a simple query tool with readOnly annotations, this is sufficient.

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 k, near, and airport_size; location lacks a description but has examples. The description adds a bit of meaning by calling location a 'named place' and noting 'scheduled service' for airport_size, but it does not significantly enhance understanding beyond the schema. With 75% coverage, the baseline is 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 returns up to 5 airports with scheduled service nearest a named place, ranked by real road drive time, with IATA codes. This is a specific verb+resource and is distinctly different from sibling tools like drive_time or entity_lookup, making it easy for an agent to differentiate.

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 on what the tool does (finding nearest airports) but does not explicitly mention when not to use it or name alternatives. However, the uniqueness of the functionality (airport location) makes usage intent obvious, so no exclusions are needed.

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 discloses pricing, payment mechanism via _meta["x402/payment"], the HTTP endpoint, and the 100-element limit, all of which go beyond the annotations. Annotations already declare readOnly and openWorld hints, and there is no contradiction; the description adds meaningful operational 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 sentences with no filler, and each sentence adds distinct information: payment mechanics and core capability. However, the payment details are front-loaded ahead of the tool's actual purpose, and the protocol jargon like 'MPP (tempo)' is dense and unexplained.

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 output schema covers return values and annotations cover the safety profile, so those gaps are acceptable. What remains missing is parameter formatting guidance, clarification of the near parameter, and explicit usage differentiation from drive_time. This is workable for a prepared agent but not fully self-sufficient.

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%, so the description needed to explain origins, destinations, and near, but it only indirectly references origins and destinations and never explains their expected format. The combined 100-element cap is useful, but near is completely undocumented and address/coordinate semantics are absent.

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 identifies a drive-time matrix computation over origins and destinations, with an explicit 100-element cap. The contrast with the sibling drive_time tool makes clear this is the multi-pair matrix variant, though it lacks an explicit verb like 'compute' or 'calculate'.

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: a matrix for up to 100 origin-destination elements. However, the description never explicitly says when to choose this over drive_time or mentions any exclusions or alternative routing. An agent must infer the distinction from the tool names and the word 'matrix'.

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 openWorldHint=true, covering the read-only nature and open-world assumption. The description adds the critical cost and payment requirement ($0.01 per call via x402) and the MPP endpoint, which are not in annotations. However, it does not disclose response format, rate limits, or error behavior. Given the annotations carry the safety profile, the description adds some value but not extensive 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?

The description is relatively concise, though it mixes payment details with the core purpose. The first sentence states the purpose, then the payment info follows. It is not overly verbose, but the payment info could be considered secondary. The structure is acceptable, though the purpose could be front-loaded more clearly.

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?

There is an output schema (though not shown), so return format may be covered there. However, the description omits details like the difference from drive_matrix, any prerequisites (e.g., valid place names), and how errors are handled. The payment requirement is covered, but other operational context is lacking. For a tool with moderate complexity and a sibling tool that is clearly related, more guidance is needed.

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 only 33%, with only the 'near' parameter having a description. The description adds minimal semantics: it says 'two named places' but does not explain that origin and destination are place names or how to format them. It doesn't clarify the 'near' parameter beyond what the schema provides. With low coverage, the description should compensate but does not, leaving the agent uncertain about parameter usage.

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 core function: 'Driving time/distance between two named places.' It names the resource (driving time/distance) and the operation (compute between origin and destination). However, it does not explicitly differentiate from the sibling drive_matrix, which likely computes a matrix of times/destinations, so the agent might not immediately know when to choose this over the matrix version.

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 provides no guidance on when to use this tool versus alternatives like drive_matrix. It only mentions the payment method, not the scenarios where a single route query is preferred over a matrix. There is no mention of limitations, prerequisites, or typical use cases. An agent would have to infer usage from the name and schema.

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 openWorldHint, so the bar for added behavioral detail is lower. The description goes beyond them by disclosing the per-call cost, the x402 payment mechanism with the required metadata path, the endpoint, the max of 10 entities, the returned fields, and the surprising fact that an empty result is still a paid 200. This is substantial, non-obvious 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?

Every sentence earns its place: pricing, payment routing, resource and query keys, states, limits, and paid-empty behavior. It front-loads the cost and payment requirement, which is exactly what an agent needs to know before invoking, and contains no wasted prose.

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 is largely complete for invocation: payment, endpoint, states, query parameters, limits, and return-field categories are all present, and the output schema exists to document return structure. The only notable ambiguity is 'Up to 10 entities'—whether that applies to input batch size, response size, or something else is not fully specified.

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 0% schema description coverage, the description must carry the semantic weight. It explains that name means exact name and entity_number means a registry entity number, and 'Served states: FL, OR' maps to the state enum. It does not explicitly tie each property to its schema field or clarify the meaning of 'Up to 10 entities' relative to the single-object input, but it compensates for the bare schema better than most.

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 resource: state business-registry records, and the query keys: entity number or exact name. It also lists the served states, which differentiates it from license- and transport-oriented siblings. However, the core sentence lacks an explicit verb like 'retrieve' or 'look up', leaving the action to be inferred from the tool name.

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 concrete conditions for use: only FL and OR, and only by entity number or exact name. This establishes when it is appropriate and implicitly rules out other states or fuzzy name matching. It does not explicitly name alternatives or say 'use license_search for licenses', but the domain is clear enough from the sibling set.

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 extensively discloses behavioral details beyond the readOnlyHint annotation: the $0.10 cost, x402 payment mechanism, the fact that empty results are still a paid 200, the hard limit of 25 results, active-first ordering, and total_matches field. This is exactly the kind of non-obvious behavior an agent needs to know before invoking.

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 information-dense and front-loads the critical cost/payment details. Every sentence contributes, though the trade lists are duplicated from the schema and add length. Still, it is well-structured and avoids 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?

Combining the description with the input schema, output schema, and annotations, the agent has the required state/trade, optional city/zip, limit and active filtering, cost/payment, result cap, and sorting. The presence of an output schema covers return structure, and nothing essential for correct invocation is omitted.

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 schema coverage at 50%, the description partially compensates for undocumented limit and active_only behavior via 'Up to 25 results, active first.' It repeats trade lists already in the schema and adds no new detail for state. The city/zip parameters remain better explained in the schema, so the added value is mild.

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 tool as a search for licensed contractors by trade and city/zip, listing output fields. The phrase 'Up to 25 results, active first' signals a list-returning search, but it does not explicitly contrast with the sibling license_verify, so it falls short of full differentiation.

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 states what the tool searches (licensed contractors by trade and location) and the allowed states/trades, which implies when it is appropriate. However, there is no explicit when-not-to-use guidance or reference to alternatives such as license_verify for single-license checks, leaving usage mostly implied.

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?

This goes well beyond the readOnlyHint/openWorldHint/idempotentHint annotations: it discloses the exact price, payment path, HTTP URL, and the important edge case that 'Empty licenses is a paid 200.' The schema description adds that invalid bodies are refused before the 402 charge, which is valuable behavioral context for a paid tool.

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 compact and information-dense: pricing, payment path, purpose, state coverage, and the empty-result edge case each get a single clause or sentence. No sentence is wasted, and the most operationally critical facts are 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?

The description covers payment, state scope, and result edge cases well, and an output schema exists to document return values. However, it lacks guidance on how to construct a valid request (parameter semantics) and does not position the tool relative to license_search, leaving meaningful gaps for an agent deciding how to call it.

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%, so the description must compensate, but it never explains the three parameters. The phrase 'Contractor license status plus matching business-entity record' weakly implies name/license_number identify the contractor, but it does not say whether they are alternatives, both required, or how they relate to the required state field.

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 the tool's core function: returning 'Contractor license status plus matching business-entity record,' and clarifies geographic scope with 'Served states: FL, OR.' However, it lacks an explicit verb and never differentiates itself from the sibling tool license_search, so it stops short of a 5.

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 usage context by naming the served states (FL, OR) and the mandatory payment mechanism (x402/MPP), so an agent knows whether it can use the tool. It does not mention alternative tools or explicitly state when to prefer license_search or entity_lookup, leaving some selection guidance implicit.

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 openWorldHint, so the read-only safety profile is established. The description adds valuable behavioral context beyond the schema: the exact per-call cost, the required payment via x402 USDC on Base, the _meta field where payment must be supplied, and confirmation that it is the cheapest paid call.

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 extremely concise at two sentences and contains no filler. It packs cost, payment routing, and purpose into a compact form that an agent can parse quickly.

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 zero-parameter tool with an output schema and clear annotations, the description covers the essential invocation details: payment amount, payment mechanism, where to provide payment, and what the call validates. It could be slightly clearer about what 'pipe' refers to, but nothing critical is missing for an agent to invoke it.

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 description coverage is 100%, so the schema has no gaps. The description still adds context by explaining that payment is passed in _meta and that no regular inputs are needed, which is helpful for an agent deciding how to invoke it.

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 identifies the tool as a low-cost paid call that 'proves wallet, 402 and receipt work', giving agents a concrete sense of what it does: verify the x402 payment path. It is not a fully explicit verb+resource statement like 'tests payment connectivity', but it is specific enough to separate it from the unrelated sibling tools such as drive_matrix and license_verify.

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 implies when to use the tool: when you need to verify that wallet, 402 payment, and receipts work at the lowest cost. However, it does not explicitly state when not to use it, mention alternatives, or explain how this relates to the sibling tools.

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