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

With no annotations at all, the description carries the full burden, and it does disclose the key behavioral trait: the manifest is persisted as a draft and is not sent to CBP. It says nothing about whether an id is returned for later update/submit, duplicate-manifest behavior, validation against CBP rules, or permission requirements.

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 short sentences, front-loaded with the action and its critical state qualifier, with zero filler. The second sentence exists only because the manual-submit constraint is non-obvious.

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 mutation tool with a rich nested schema, no annotations, and no output schema, the description covers the draft-versus-submit distinction but leaves the agent guessing about the response (is a manifest id returned?) — information needed to later call update_manifest. Adequate but with a clear operational gap.

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 nested fields are individually documented, so the baseline is 3. The description adds no meaning about the two top-level parameters (fields, occupants) beyond what the schema already explains, such as occupant ordering intent or required-field minimality.

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 (create a new manifest) and scopes it precisely as a DRAFT that is saved but not submitted to CBP/eAPIS. It does not name a sibling such as update_manifest or list_manifests to route the agent, relying on the natural create/update distinction instead.

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 parenthetical 'saved, NOT submitted' plus 'Submitting stays a manual step on flashpass.net' tells the agent this is the creation endpoint and that no submit tool exists, which prevents a wasted search. It stops short of stating prerequisites (e.g. whether flight fields must be complete before creation) or how it relates to update_manifest afterward.

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 behavioral burden. It reveals that this is a write operation, but does not describe duplicate handling, required fields beyond the top-level fields object, permission requirements, or what the response contains.

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 front-loaded sentence with no wasted wording. It states the action, resource, scope, and domain context efficiently.

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 rich schema covers the nested person fields, and no output schema exists to explain. However, for a mutation tool with no annotations, the description is still thin on behavior such as duplicate detection, required identity fields, and response shape.

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 nested field schema already documents the available properties and their formats. The description adds no additional meaning about the fields object or individual person attributes, making the baseline 3 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 and resource: adding a new person to the FlashPass address book, with the passenger/crew scope clarified. This clearly separates it from get_person, list_persons, and update_person, although it does not explicitly name those 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 only guidance is implied by 'Add a new person.' There is no explicit when-to-use guidance, no mention of when to prefer update_person instead, and no prerequisites or exclusions for creating a person.

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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context. It does disclose the shape of the payload (flight fields plus occupants with name, duty, US address), which hints at sensitive personal data, but it never states that the response contains PII or what happens if the id is unknown. Modest added value over the 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?

One short sentence, front-loaded with the action and then the payload, with zero filler. It is arguably too terse given the under-specified id, but nothing in the wording is 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?

For a single-parameter read tool with no output schema, the description roughly maps the return payload, which is the main gap it needed to fill. However, it leaves the id's referent ambiguous and gives no guidance for choosing it over list_manifests, so it is only adequate.

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?

There is a single required parameter, id, with 0% schema description coverage, so the description must explain it. It implies the id identifies a manifest via the singular 'a manifest' framing, but never states which entity the id refers to (manifest, flight, or draft) or its format. Partial compensation 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 names a specific verb and resource ("Get a manifest") and enumerates the returned content — flight fields and occupants with name, duty, US address — which tells an agent what this tool surfaces. It does not explicitly distinguish itself from list_manifests or get_person, so routing relies on the singular phrasing plus the id parameter.

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?

There is no guidance on when to use this versus list_manifests (browse) or create_manifest_draft/update_manifest (mutation), and no prerequisites or exclusions. The 'Get' verb implies retrieval, but the choice among the manifest siblings is left entirely to inference.

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 readOnlyHint annotation already establishes this is a safe read, and the description adds relevant behavior by noting the response includes all fields plus travel documents (i.e., no projection or field selection). It says nothing about behavior when the id is unknown, permissions required, or response size, so the added context is modest.

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 key detail (all fields, including travel documents) is stated immediately. It is efficient, if sparse.

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 does the minimum by sketching the return shape (all fields, plus travel documents). However, for a lookup-by-id tool it leaves the id's meaning and not-found behavior unaddressed, so it is only adequate.

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 single parameter is named "id" with 0% schema description coverage, so the description must carry the meaning — but it never states that the id is a person identifier or what format it takes. The one behavioral hint (travel documents are included) concerns output, not the parameter.

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 ("Get ... a saved person") and clarifies the scope of the return (all fields, including travel documents). It is clearly distinct from list_persons by being singular, though it never names that sibling or otherwise differentiates itself explicitly.

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?

There is no guidance on when to use this tool versus list_persons for discovery or update_person for modification. The phrase "saved person" faintly implies the record must already exist, but no prerequisites, alternatives, or exclusions are 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?

The readOnlyHint=true annotation already establishes that this is a safe, non-mutating read. Beyond that, the description adds almost nothing: it does not clarify whether results are paginated, whether the list is unfiltered/complete, or what "ids" refers to. The one hint — that ids are surfaced — is left ambiguous rather than explained.

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?

One short phrase, front-loaded with the verb and resource — no wasted wording. The only cost is that the brevity produces ambiguity in "with ids" rather than crispness.

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 read-only list tool with annotations covering its safety profile, this is close to minimally sufficient. Still missing is any sense of what a result entry contains or whether the listing is complete, which matters because there is no output schema to fall back on.

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 takes zero parameters, so there is no parameter meaning for the description to add; per the baseline rule this scores 4. The stray "with ids" phrasing arguably muddies rather than clarifies the (empty) parameter situation.

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?

"List aircraft with ids" gives a specific verb (list) and resource (aircraft), so the basic operation is identifiable. However, the phrase "with ids" is ambiguous — it could mean an id parameter, id-based filtering, or that ids are included in the response — and nothing distinguishes this from siblings like list_persons or list_manifests beyond the resource 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?

There is no when-to-use guidance, no mention of alternatives such as update_aircraft or the manifest tools, and no stated preconditions. The only implied usage is 'list aircraft', which an agent could already infer from the name alone.

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 readOnlyHint already establishes this is a non-mutating read, so the description's job is lighter. It adds the useful detail of which fields come back, but says nothing about result volume, pagination, ordering, or whether all manifests are always returned — notable gaps for a parameterless list 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?

A single front-loaded sentence with no filler; every word (verb, resource, returned fields) carries information. Nothing could be trimmed without losing content.

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 parameters and no output schema, the description partially compensates by naming the returned fields, which is genuinely useful. However, it omits the operational facts an agent would want for a parameterless list call — whether results are paginated, capped, or ordered — leaving the definition only marginally complete.

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?

There are zero input parameters, so there is nothing for the description to disambiguate; baseline is 4. The enumerated fields are output-side information rather than parameter semantics, which is a bonus rather than a requirement here.

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 ('List') and resource ('manifests') and enumerates the fields the listing includes (id, aircraft, route, leg, status, arrival date). It is clearly distinct from get_manifest by name, but the description itself does not explicitly contrast the two.

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 only implied: an agent can infer this is the bulk-listing counterpart to get_manifest, but the description never says when to use this versus get_manifest or any filtered alternative. No prerequisites or exclusions are 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It says nothing about result caps, pagination, ordering, or whether a missing search term returns everything — the main behavioral questions for a list tool remain unanswered.

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?

One short sentence with zero filler, leading with the action and resource. Nothing could be trimmed without losing scope 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 simple read-only list with one optional parameter and no output schema, the description is minimally sufficient to call the tool. It still leaves open whether results are paginated or complete, which matters when deciding whether to filter server-side.

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% with a single optional "search" parameter already described as a "Name substring filter." The description adds no further meaning about matching behavior, but the schema carries the burden fully, so the baseline 3 applies.

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?

"List saved persons (passengers/crew) with their ids" gives a specific verb and resource, and clarifies the domain objects plus what is returned. It is distinguishable from siblings like get_person and create_person, though it never names them explicitly.

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?

There is no guidance on when to use this versus get_person, nor whether it is meant for lookup-by-id or browsing. The phrase "with their ids" faintly hints the tool is a discovery step, but that is inference rather than instruction.

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 behavioral burden, and it discloses almost nothing: no permission requirements, no statement of whether the update is partial/merge or full replacement of the fields object, no irreversibility warning, no error behavior. The only behavioral hint is the word 'Change', which implies mutation but nothing more.

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, which is the right shape for this tool. The parenthetical field list is largely redundant with the schema property names, so it is efficient but not maximally informative.

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 mutation tool with a nested object parameter, zero annotation coverage, no output schema, and 0% schema description coverage, the definition is far too thin. An agent cannot determine merge-vs-replace semantics, required permissions, or what a successful response contains before invoking 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% and the nested 'fields' object has seven properties whose descriptions are tautologies ('Color', 'Tail', 'Call sign'). The description merely restates six of those property names and even omits TailNumber, which the schema accepts, and it never explains what 'id' identifies or whether unspecified fields are preserved.

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 ('Change') and resource ('aircraft fields') and enumerates the mutable fields, so an agent can tell this apart from update_person or update_manifest by resource alone. It stops short of any explicit sibling differentiation or statement of scope (single aircraft vs batch).

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 no when-to-use guidance, no prerequisites, and no alternatives. It never says whether this is the tool for correcting a tail number versus creating an aircraft (create_person-style siblings exist for other resources, but no create_aircraft appears here), leaving the agent to infer usage entirely from the name.

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 supplied, the description carries the full behavioral burden, and it discloses the single most important trait: the operation saves only and never submits to CBP, plus the consequence that a previously submitted manifest needs manual re-submission. It stops short of covering reversibility, whether omitted fields are preserved, or how already-submitted manifests behave on edit.

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 mutation scope and immediately followed by the critical non-obvious constraint. No filler and nothing 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 no-annotation mutation tool with a nested schema and no output schema, the description covers what changes, what does not happen (no CBP submission), and the follow-up consequence. It lacks any note on partial-update semantics or the result of the call, which keeps it shy of a 5.

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 loosely onto the top-level parameters (flight fields, add occupants, remove occupants) which helps orient the agent. With schema coverage around 50% and a deeply nested object of flight fields, duty enums, and occupant identity options, the description adds no detail beyond that coarse mapping — the specifics live in the schema or nowhere.

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 gives a specific verb and resource ("Change a manifest") plus an enumeration of what can be changed: flight fields, occupants added and/or removed. That is far more concrete than the bare name. It does not, however, name a sibling such as create_manifest_draft or get_manifest, so the agent must infer the boundary from the name 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?

Usage is implied by the "Change a manifest" framing and the note that an already-submitted manifest must be re-submitted manually, which tells the agent this is the edit path for an existing manifest. There is still no explicit statement of when to use this versus create_manifest_draft or get_manifest, and no stated prerequisites such as the manifest needing to exist.

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 at all, the description carries the full burden. It does disclose the key patch semantic — "Only the fields you pass are changed" — which is real behavioral value an agent could not otherwise know. It says nothing about permissions, what happens when id does not match a person, whether a field can be cleared (empty string vs. null), or whether the object is merged deeply or shallowly.

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 short sentences, the mutation verb and resource front-loaded, and the patch semantics stated immediately after. No filler whatsoever.

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?

This is a mutation on a nested 26-field object with zero annotations and no output schema, so the description must supply the behavioral context itself. It does not state the return value (updated person or nothing), permission requirements, failure modes for a bad id, or how to unset a field — gaps that matter for a write operation of this shape.

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 50% and the nested fields object has 26 properties, several without descriptions. The description adds one meaningful clarification — that omitted fields are left untouched, so the object acts as a partial patch, not a replacement. The id parameter is left completely unexplained (internal vs. external identifier format), which is a notable 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?

"Change fields of an existing person" gives a specific verb and resource, and the qualifier "existing" implicitly separates it from create_person in the sibling set. It does not name any sibling explicitly, so differentiation is left partly to inference.

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 second sentence implies this is the tool for partial modifications rather than full replacement, which is usable guidance. However, there is no explicit statement of when to prefer update_person over create_person, nor any prerequisite such as the person having to exist or be fetched first via get_person.

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