Verified Reality

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

With no annotations present, the description carries the full burden and delivers the key behavioral facts: the call only queues for HQ review, it is NEVER auto-dispatched to a human Verifier, and a bearer API key is required. It stops short of idempotency/retry behavior or error conditions (e.g., expired or already-used quote_id), which are the remaining gaps.

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: the action and its source first, then the resulting state and the negative guarantee. No redundant restatement of the name or title, and the critical 'NEVER auto-dispatched' clause is emphasized rather than 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?

For a one-parameter submission tool with no output schema, the definition covers source, resulting state, authorization, and the key non-behavior (no human dispatch). Only edge-case behavior such as duplicate submissions or invalid/expired quote_ids is unaddressed.

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; it does add the provenance of `quote_id` (it comes from `quote_field_bounty`), which the schema does not state. It does not add format, freshness, or expiry semantics beyond the schema's UUID pattern, so compensation is partial.

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 action (submit a quote_id to queue a field-verification bounty), the resulting state (`pending_review`), and names the originating sibling `quote_field_bounty`. An agent can distinguish this from `quote_field_bounty` and the other siblings 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?

Makes the prerequisite explicit: the quote_id must come from `quote_field_bounty`, which tells the agent this is the second step in a workflow. It lacks an explicit 'do not call before quoting' exclusion or any note on what happens on repeat submissions, but the sequencing context is clear.

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?

No annotations are supplied, so the description carries the full burden; it does disclose the auth requirement and that the quote is 'dynamic' (i.e., computed per packet). It says nothing about whether a quote is persisted, whether repeated calls are idempotent, or how the result is shaped, leaving meaningful behavioral gaps for a no-annotation 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?

Two sentences, zero padding, with the core action first and the prerequisite and auth notes trailing. Every clause carries information an agent needs.

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 no-annotation, no-output-schema, 0%-coverage tool, the definition covers enough to attempt the call (packet lookup, license type, auth) but not enough to predict the response or understand usage_details. Adequate to invoke, thin for interpreting results.

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; it usefully explains where packet_id comes from and maps the two license flavors to the license_type enum. usage_details, a free-form string, gets no explanation at all, and the UUID format constraint is left entirely to 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?

States a specific verb ('Generate') and resource ('licensing quote') and narrows scope to 'a specific Exchange packet', with the two license flavors named. It does not differentiate itself from the sibling quote_field_bounty, which sounds closely related, so an agent cannot fully rule it in or out on purpose alone.

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 a concrete prerequisite workflow ('find packet_id via search_catalog first') and an access precondition ('Requires a bearer API key'), which is more than most definitions offer. It stops short of saying when to prefer this over quote_field_bounty or what to do if no packet matches.

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?

With no annotations, the description usefully discloses the bearer API key requirement, the limited quote-only behavior, the handoff to dispatch_field_bounty, and geographic availability constraints. It does not mention quote expiration, pricing or currency behavior, or whether travel-dependent requests incur special handling, so some behavioral detail remains unspecified.

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 purpose is front-loaded, followed by authentication, the quote-versus-dispatch distinction, and coverage limitations. Each sentence supplies actionable information without redundant wording.

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 definition provides the essential selection and invocation context: purpose, authentication, next-step workflow, and service availability. Its remaining weaknesses are the limited parameter guidance and lack of detail about quote validity or returned pricing, which matter because there is no output schema.

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?

Beyond the schema, the description only loosely connects the inputs to "a location"; it does not explain how lat, lng, and radius_meters define the quoted area or provide guidance for the verification description. With schema description coverage at 25%, this leaves a meaningful gap, although the coordinate and radius parameter names are partly self-explanatory.

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 verb, resource, and scope: quoting a human field verification at a location. It also distinguishes this tool from dispatch_field_bounty by emphasizing that it only creates a quote rather than submitting the bounty.

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 an explicit workflow: use this tool for the quote, then call dispatch_field_bounty with the returned quote_id to submit. The southwestern Ontario coverage statement and warning that other cities are not guaranteed on demand further help the agent judge when the tool is viable.

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?

With no annotations, the description carries the full disclosure burden, and it does add two genuinely useful facts: a bearer API key is required on the MCP HTTP request, and an empty result means 'no match' rather than 'verified clean' — a distinction that could easily cause a wrong conclusion. It says nothing about rate limits, result shape, or how pagination interacts with a large match set.

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, front-loaded with the scope statement, and the auth requirement is placed before the result caveat. No filler, though the empty-result sentence is slightly long-winded relative to the point it makes.

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?

Seven parameters, no annotations, and no output schema, so the description must shoulder a lot — and it does not describe what a Truth Packet result contains or how offset/limit relate to a total count. The auth and empty-result notes cover the two highest-risk misunderstandings, leaving the definition adequate but incomplete for a discovery tool with no output schema.

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 86%, so the schema already documents q, lat, lng, radius, limit, and offset well enough for correct invocation. The description adds no parameter-level meaning (no note on how tier values like ENCRYPTED affect licensing, or that geo filters require all three of lat/lng/radius). Baseline 3 applies 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 (search) plus a tightly qualified resource: 'HQ-approved, opted-in Truth Packets available for commercial licensing.' That is far more precise than the bare name 'search_catalog' and implicitly separates it from siblings like generate_license_quote or verify_media_hash. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

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 by the licensing framing rather than stated: an agent can infer this is the discovery step before quoting or dispatching a bounty, but no when/when-not or alternative routing is given. The only explicit guidance concerns interpreting an empty result set, which is result semantics rather than selection 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?

With no annotations, the description carries the full burden and does well: it discloses the auth-free access model and, importantly, scopes the meaning of a match to byte integrity only, explicitly excluding scene honesty, completeness, or admissibility. It does not say what a mismatch produces (error vs. a negative result) or what the response payload looks like, which leaves a real behavioral gap for a verification 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?

Three short sentences, front-loaded with the core action before the supporting scope and the caveat. Every clause earns its place, and the interpretive limitation is placed last where it reads as a qualifier rather than burying the primary instruction.

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 three-parameter verification tool with no annotations and no output schema, the description covers purpose, preconditions, auth, and the semantic limits of a positive result. The one missing piece is the shape of the return value, which the absence of an output schema forces the description to carry and it does not.

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 hash format, the kind enum, and the truth_packet_id scoping are already fully documented. The description restates the same three file kinds without adding format, precedence, or conditional-requirement detail beyond the schema. Baseline 3 applies 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 precise verb and resource: re-check that a file's bytes still match Verified Reality's registry for a prior sealed reference. It enumerates the three supported file kinds (media, Truth Packet zip, certified audit PDF), so an agent knows exactly what input domain this covers. No sibling tool overlaps this verification role.

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 a prior sealed reference' establishes the precondition: a hash must already exist in the registry, making this a re-verification rather than a first-time seal. It also clarifies that no API key is needed, removing an auth step from the agent's plan. It stops short of stating what to do when no prior reference exists or naming any alternative tool.

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