BEACON by Owner Connect

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

Beyond the annotations, the description discloses the data source (the operator's connected calendar), freshness (synced every 15 minutes), output granularity (free or taken per day, never what is scheduled), and an error path when the owner does not publish availability. This gives the agent rich behavioral context for a read-only tool without contradicting any annotation.

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 a single dense sentence with no filler, and the availability-checking purpose is front-loaded. The phrasing is slightly convoluted — 'read from the operator's calendar its owner connected' — but every clause carries useful information.

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 read-only availability check with no output schema, the description covers the return semantics, data freshness, date-span limit, and the case where availability is unpublished. Combined with annotations that already confirm safety and idempotency, 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?

The schema already describes all three parameters, so the baseline is 3. The description adds meaningful context not in the schema: the 14-day maximum span for end_date and the typical departure/return interpretation for date and end_date.

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-plus-resource: checking whether one aircraft has anything scheduled on a date or across a date span. It clearly separates this from sibling operations such as searching aircraft or requesting a trip by focusing on calendar availability, not aircraft attributes or booking actions.

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 to call the tool when the user asks whether an aircraft is available, including departure and return dates for round trips. It also states what the tool is not — 'Not a hold and not a confirmation' — but does not name a specific sibling tool to use for holds or confirmations, keeping it just short of a 5.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real context on top: positioning is included only when the owner bills it, the figure is not a quote and not binding, the result is a sentence to relay verbatim, and the tool returns a reason rather than a figure when no terms or rate are published. That failure-mode disclosure is exactly what an estimating tool needs.

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?

Purpose is front-loaded in the first clause and every subsequent sentence carries a distinct instruction (trigger, retry, response handling, disclaimer, failure mode). The phrasing is idiosyncratic in places ('the beacon works out the legs', 'Answer with its sentence') but no sentence is padding.

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 five-parameter, read-only estimation tool with no output schema, the description covers what it returns (a sentence), what it returns on failure (a reason), how to recover, and the non-binding caveat. Nothing needed to invoke 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?

With 100% schema coverage the baseline is 3, and the description earns an extra point by explaining block_hours as a caller-supplied fallback estimate invoked only after the 'no block speed' response, and by noting positioning is folded in when the owner bills it. round_trip is left entirely to the schema, which is a minor remaining 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?

States a specific verb and resource — an approximate charter cost for one aircraft at the owner's published hourly rate — and goes further to explain how legs and block hours are derived. An agent can immediately distinguish this from siblings like request_trip or check_availability, which book rather than price.

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 an explicit trigger ('call it whenever the person you are helping asks what a trip would cost'), the required inputs (departure and arrival airports), and a precise retry path when the owner has no block speed: call again with block_hours. It does not name or rule out any sibling tool, so it stops short of full alternative routing.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the response envelope, the enumeration of status values (found, not_found, invalid, unavailable), and the conditional presence of owner_approved — all things annotations cannot convey. It does not contradict the readOnly hint.

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, front-loaded with what the tool returns before the field-by-field breakdown. The reference to /{mark}/facts.json earns its place by telling an agent the payload matches a known document shape; the repetition of case/hyphen handling is the only wasted 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?

There is no output schema, so the description carries the burden of explaining returns — and it does, enumerating the status values and the two payload branches including the conditional owner_approved field. For a single-parameter read tool this is close to complete, with only pagination/error-cadence details absent.

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 parameter is fully described in the schema, including the case and hyphen normalization. The description repeats that normalization verbatim rather than adding syntax, format, or failure-mode detail, so it is baseline value only.

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 resource (the public record for one U.S. registration mark) plus a distinct second payload (owner-approved facts), which an agent can separate from search_aircraft's multi-result behavior without opening either schema. It stops short of naming a sibling directly, so it is clear but not maximally 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 singular 'one U.S. registration mark' framing, which signals a point lookup rather than a search, and the sibling search_aircraft makes that contrast inferable. However, there is no explicit when-to-use/when-not statement and no named alternative, so an agent must infer the routing.

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 substantial behavioral context beyond annotations: it clarifies that nothing is booked or held, that the requester receives an email link, that the request is delivered only after confirmation, and that qualification questions may require a second call. This is exactly the kind of side-effect and workflow transparency needed.

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 with the core action, then immediately gives the key precondition, followed by essential behavioral details. Every sentence earns its place and there is 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 11 parameters, no output schema, and open-world annotations, the description provides a complete picture: consent requirement, no-booking guarantee, confirmation flow, and qualification-question handling. An agent has enough to invoke correctly without guessing.

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 baseline is 3. The description adds valuable workflow context for the answers parameter ('in the same order' and the first-call returns needs_answers with questions), which goes beyond the schema's own description.

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: 'Sends a charter trip request for one aircraft to the booking contact its owner named.' It clearly describes the action and target, though it does not explicitly name or differentiate from the sibling tool send_buyer_inquiry.

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 a clear precondition: 'Call it only after the person you are helping has asked to proceed, with their own name and email.' It explains the confirmation flow, but does not mention when to use alternatives like check_availability or estimate_charter.

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 readOnly/idempotent/non-destructive, so the description spends its words on non-obvious semantics instead: filters only apply to owner-cleared facts, so an aircraft with no published seat count can never match a seats filter. It also discloses the return shape (owner_approved block) versus the public record.

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, front-loaded with the resource and filter set, then the filtering caveat, then the alternative-tool routing. No restatement of the title and nothing 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?

No output schema exists, and the description nonetheless tells the agent what comes back (the owner_approved block). For a six-parameter, fully-documented read tool, nothing an agent needs to invoke 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 coverage is 100%, so baseline is 3; the description earns above baseline by adding the negative-match semantics for min_seats and the 'as the owner published it' framing that governs type and base_airport matching. It does not add format or interaction details for limit or the two boolean signals beyond what the schema states.

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 plus the exact filter dimensions (seats, base airport, type, charter/sales signal) and names the sibling it is not: 'call get_aircraft for the public record'. An agent can distinguish this from detail-fetch tools without opening either 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?

Explicitly routes to get_aircraft when the public record is needed, which is the main sibling disambiguation. It does not address the other siblings (check_availability, estimate_charter, send_buyer_inquiry), but those are clearly a different task class.

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 substantial context beyond the annotations: nothing is offered or agreed, the buyer receives a confirmation link, the message is delivered only after confirmation, and the representative replies directly. It also discloses the needs_answers qualification flow, which is important behavioral information for an open-world contact 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 front-loaded with the core action and then adds only necessary preconditions and workflow details. Each sentence contributes to correct invocation, with 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?

With no output schema, the description still explains the key response behavior: the buyer gets a link, delivery waits for confirmation, and the representative replies directly. It also covers the qualification-question branch, making the workflow complete enough for an agent to call 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?

Schema description coverage is 100%, so the schema already documents all seven parameters, including name, email, message, and answers. The description reinforces some parameter meaning, such as using the person's own details and answering qualification questions in order, but it adds little 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 states a specific verb and resource: it passes a would-be buyer's message to the owner's acquisition representative for one aircraft. This is clearly distinct from the sibling tools, which are about searching, availability, charter estimates, or requesting trips.

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 precondition: call only after the person has asked to contact the owner and has provided their own name, email, and message. It also explains the two-step qualification-question flow, so the agent knows when a second call is required.

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