Fleetio MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true; the description goes further by disclosing the notification side effect (watchers and @mentioned users are notified) and that the created comment cannot subsequently be edited or deleted through this server. It does not cover error modes or whether duplicate submissions create duplicate comments.

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 operation type and the primary side-effect warning, with zero filler. Nothing repeats and nothing is 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?

With no output schema, the description could say more about what is returned, and it says nothing about authentication or permissions needed to comment on a record. However, for a simple create-comment tool it covers the operation, the side effects, the irreversibility, and the underlying endpoint adequately, and the annotations carry the safety profile.

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 three parameters including the enum values and the 'id, not number' distinction. The only marginal addition is that @mentions inside the text trigger notifications, which touches the 'comment' parameter semantics; otherwise the enum list in the description merely restates 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?

Starts with a WRITE marker then states a specific verb+resource ('add a comment') and enumerates every supported record type, which mirrors the commentable_type enum. An agent can immediately distinguish this from the read-side sibling fleetio_list_comments.

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 'WRITE:' prefix and the enumeration of commentable records clearly signal the context in which to call it, and the statement that comments 'cannot be edited or deleted by this server' implicitly warns that this is a one-way operation. It never names an alternative tool or states explicit exclusions, so it stops 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 declare readOnlyHint=false and destructiveHint=true, so the safety bar is partly covered. The description adds genuinely new behavioral context: watchers/assignees may be notified, and report time defaults to now. It also states the tool does not delete/resolve, refining the destructive 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?

Front-loaded with a 'WRITE:' marker and a clear verb+resource lead, then tight supporting sentences. The scope disclaimer sentence is slightly redundant but still earns its place as disambiguation.

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 9-parameter write tool with full schema coverage and no output schema, the description covers required inputs, side effects (notifications), defaults, and the API endpoint. It leaves minor gaps (e.g., auth/permission requirements) but is largely 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?

Schema coverage is 100%, so the schema already documents all 9 parameters. The description adds value by naming the two required fields and cross-referencing fleetio_list_vehicles for asset_id and defaulting the report time, though the default is already noted in 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 ('create') and resource ('a new issue (a reported defect)') with its scope ('on a vehicle or equipment'). An agent can distinguish it from siblings like fleetio_get_issue and fleetio_list_issues without opening any 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?

Explains what the call needs ('the asset id ... and a summary') and clarifies scope ('Does not close, resolve or delete anything'). It provides clear context but does not explicitly route between alternatives or name exclusions beyond the scope disclaimer.

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 flag write/destructive/non-idempotent, and the description adds context an agent cannot get from them: server-side sequence validation, non-deletability from this tool, date defaulting to now, and the downstream side effect that a reading can make service reminders due/overdue and may notify watchers. This is exactly the beyond-annotation disclosure the dimension rewards.

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?

Front-loaded with 'WRITE:' to set the operation class, then each clause (primary/secondary, sequence rule, non-deletability, date default, side effects, endpoint) carries distinct information. No 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?

Covers purpose, constraints, side effects and the endpoint well for a 4-param create tool with no output schema. The only gap is that it never hints at the return shape (e.g., the created entry id an agent would need for follow-up calls).

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 date, value, secondary and vehicle_id. The description reinforces secondary/primary and the date default but adds no syntax, unit conversion, or format detail the schema lacks. Baseline 3 is 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?

States a specific verb+resource ('record an odometer / engine-hour meter reading for a vehicle') and immediately disambiguates the primary vs. secondary meter case. Against a sibling set dominated by fleetio_list_meter_entries / list_vehicle_meter_entries, it is unmistakable that this creates rather than lists.

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 clear context for when this applies (recording a reading) plus key constraints (sequence-breaking values are rejected; 'it cannot be deleted from here'). It does not explicitly name an alternative tool or state when NOT to use it, so it falls 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds a real behavioral trait beyond annotations: birth date and driver-licence data are never returned, which tells the agent what to expect in the response.

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 terse fragments, front-loaded with the resource identity and followed by the key data limitation and the underlying endpoint. No filler, though the endpoint path is only marginally useful to an agent.

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?

A read-only single-resource lookup with one fully documented parameter and no output schema. The description covers the resource, the notable field exclusions, and the call target, leaving little ambiguity for 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?

There is one parameter with 100% schema description coverage, so the schema already carries the parameter documentation. The description adds nothing about the contact_id format beyond what the schema shows, which is the expected baseline for full schema coverage.

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 (GET) and resource (one contact), and clarifies what a 'contact' is (driver/technician/employee). The singular 'One contact' implicitly distinguishes it from the sibling fleetio_list_contacts, but the differentiation is not stated 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?

Usage is only implied via the singular 'One contact' versus the list_contacts sibling. There is no explicit statement of when to use this lookup by ID versus searching with list_contacts, and no prerequisites are mentioned.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that the response is a complete record ('full detail'), with no mention of auth requirements, rate limits, or error behavior for a missing id.

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 brief sentences with zero filler, and the core purpose is front-loaded ahead of the endpoint mapping. Nothing is redundant.

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 read tool this is close to sufficient, but with no output schema the description's 'full detail' is the only hint about the return shape and remains vague. It is adequate but does not fully compensate for the absent 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 100%, so the equipment_id parameter is fully documented in the schema and the baseline is 3. The 'GET /equipment/{id}' fragment confirms the id is a path identifier but adds no format or constraint detail beyond what the schema already provides.

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 clear resource (one equipment record) and scope (full detail, singular), which distinguishes it from fleetio_list_equipment by implying a single-record fetch. It does not name the sibling explicitly, so it stops short of 5 despite being immediately understandable.

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?

No when-to-use statement, no prerequisites, and no mention of the list_equipment alternative. The singular-vs-list distinction is only inferable from the phrasing 'One equipment record', which is thin 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the payload includes the template's items, which is genuinely useful return-shape context, but says nothing about permissions, rate limits, or pagination.

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 with no filler; the content-bearing statement ('with its items') comes first and the endpoint path follows as supporting detail. Nothing wasteful, though the endpoint path is largely redundant with the tool name.

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 usefully signals that the return is a single template plus its items. For a one-parameter read tool with full annotation coverage, this is close to sufficient, though it could note what an 'item' contains or how to obtain the id.

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% for the single inspection_form_id parameter, so the schema carries the parameter burden. The description adds no format or sourcing details (e.g., where the id comes from), which is acceptable given full coverage.

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 (get) and resource (one inspection form template), and the plural/singular distinction from fleetio_list_inspection_forms is implied by 'One'. It does not, however, explicitly differentiate itself from fleetio_get_submitted_inspection, which is a different but similarly named retrieval tool.

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 fleetio_list_inspection_forms (browse templates) or fleetio_get_submitted_inspection (retrieve a filled-out inspection). The agent must infer the selection criteria 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the set of fields (state, priority, asset, reporter, due date, resolution) and the optional expansion via includes, which is modest additional context but says nothing about auth scope or payload size when includes are used.

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 compact sentences plus an endpoint fragment, front-loaded with the resource and its contents. 'GET /issues/{id}' is mildly redundant with the tool's REST mapping but costs almost nothing and confirms the identifier semantics.

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 carries the return-value burden and does so by naming the fields returned; includes-driven expansions are listed too. It is adequate for a simple two-parameter read tool, though it omits what the payload looks like when includes are supplied.

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 both parameters are documented in the schema, including the important 'Issue id (not the issue number)' clarification. The description restates the includable categories already present as the enum, adding no syntax or format detail, so 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?

States a specific verb+resource implicitly ('One issue with full detail') and enumerates the returned attributes, so an agent can distinguish it from the sibling fleetio_list_issues by the singular scope. It stops short of naming the sibling explicitly the way a 5 would.

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 field list and 'GET /issues/{id}' — fetch one issue by id — but there is no explicit when-to-use versus fleetio_list_issues, no prerequisites, and no stated conditions for choosing includes.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by naming the returned detail fields and the underlying endpoint, which partially compensates for the absent output schema, but it discloses no further behavior such as error/not-found handling.

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 compact fragments, front-loaded with the resource and return scope before the endpoint reference. No sentence is wasted and nothing is 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 single-parameter read tool with annotations covering the safety profile and no output schema, the description supplies the returned field list and the endpoint, which is nearly everything an agent needs. The only gap is explicit routing against the sibling list 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 100% for the single part_id parameter, so the schema already documents it. The description adds nothing about the id's format or the integer-vs-string duality present in the schema, so baseline 3 is 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 gives a specific verb+resource ('get' + 'part') and enumerates the fields returned (number, manufacturer, category, costs), which goes beyond the bare title. The singular 'one part' implicitly distinguishes it from fleetio_list_parts, but it never names that sibling explicitly, so differentiation is left 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 phrase 'One part with full detail' implies the single-record retrieval use case versus the list variant, but there is no explicit when-to-use statement, no prerequisite (e.g. needing a valid part_id), and no named alternative. Usage is implied rather than 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by disclosing what the response contains (vehicle, vendor, notes, meter readings, totals) and the underlying GET endpoint, which matters because there is no output schema.

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, zero filler, with the resource and its returned detail front-loaded before the endpoint reference. Every clause earns its place.

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 annotations covering safety and no output schema, the description is nearly sufficient because it enumerates the fields returned. It could still be tighter by noting the id is retrievable from fleetio_list_service_entries, but nothing critical 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?

Only one parameter, service_entry_id, and schema description coverage is 100% ('Service entry id.'), so the schema does the work. The description adds no format or sourcing detail (e.g., that the id can be an integer or numeric string, or where to obtain it), so this sits at the baseline.

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+resource ('Get service entry' / 'One service entry') and enumerates the detail returned (vehicle, vendor, notes, meter readings, totals). The singular 'One service entry' implicitly contrasts with the fleetio_list_service_entries sibling, but no sibling is named explicitly, 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?

Usage is only implied: fetching a single known entry by id rather than browsing. There is no explicit when-to-use statement, no mention of when to prefer fleetio_list_service_entries, and no prerequisites (e.g., needing an id obtained from the list tool).

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description earns credit by disclosing the response composition (per-item pass/fail/remarks, associated vehicle, driver, resulting work order) and the underlying endpoint, which is meaningful behavioral context for a read with no output schema.

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 payload description is front-loaded and the endpoint reference trails as supporting detail. No filler or repetition of the title.

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 supplies the return-content detail an agent needs and the annotations supply the safety profile. Only error/not-found behavior and explicit sibling routing are absent, which are minor here.

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?

Only one parameter and schema coverage is 100%, with the schema documenting it as 'Submitted inspection form id.' The description adds no format, id-type, or lookup guidance beyond that, 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?

States a specific verb+resource ('One submitted inspection') and enumerates the payload (item results, vehicle, driver, work order), which cleanly separates it from fleetio_list_submitted_inspections. It does not explicitly distinguish itself from the similarly-named fleetio_get_inspection_form, but the singular 'submitted' framing makes the intent readable.

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: fetch a single submitted inspection by its id. There is no explicit when-to-use, no when-not-to-use, and no mention of the list sibling as the alternative for browsing. Adequate but leaves routing 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety and mutability are covered. The description adds the endpoint and the shape of returned fields, but says nothing about auth requirements, rate limits, or error behavior when an id is not found.

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 compact sentences, front-loaded with the resource scope and followed by the endpoint; every clause conveys information (returned fields, API path) with no 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 usefully enumerates the fields returned (status, type, group, meters, VIN, make/model/year, plate, dates), which is the key compensation. It stops short of describing nesting or the response envelope, but is adequate for a single-record read.

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 vehicle_id parameter, including the VIN/license-plate fallback and numeric format, is fully documented in the schema. The description adds no additional parameter guidance beyond that.

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+resource ('One vehicle with full detail') and enumerates the fields returned, plus the concrete endpoint GET /vehicles/{id}. It is clearly distinguishable from list-style siblings in intent, though it never explicitly names fleetio_list_vehicles as the alternative in the description text itself.

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 usage ('One vehicle with full detail') but gives no explicit when-to-use or when-not-to-use guidance; the useful routing hint ('otherwise find the id with fleetio_list_vehicles') lives in the schema, not the description. For a single-record fetch the intent is inferable, so this is minimum viable rather than absent.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the 'full detail' nuance (contrasting with possibly abbreviated list views), revealing nothing about not-found behavior or response shape.

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 very short sentences with the purpose front-loaded and no wasted clauses. The trailing 'GET /vendors/{id}' is largely redundant REST trivia already implied by the tool name and parameter.

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 read tool whose annotations cover safety, this is close to sufficient, but with no output schema the description should carry more of the return-value burden than the vague 'full detail'. Error/not-found behavior is also 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 100% for the single vendor_id parameter, so the schema does the heavy lifting and the baseline is 3. The description adds no format, id-source, or type detail beyond what the schema already documents.

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 resource (one vendor) and scope (full detail), so an agent can tell it apart from the list-oriented sibling fleetio_list_vendors by the singular 'one vendor'. However, the description never names that sibling, so the distinction is only implicit.

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 explicit when-to-use guidance and no named alternative, even though fleetio_list_vendors is the obvious sibling an agent must choose against. The only hint is the phrase 'one vendor', which implies single-record retrieval but is left for the reader to infer.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds return-content context (status, vendor, technician, dates, totals) but says nothing about auth, rate limits, or error behavior, which is modest added value over 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 short sentences, front-loaded with the resource and followed by the endpoint. No wasted words.

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 field enumeration usefully signals what comes back, and the single required param is fully covered. Minor gap only: no note about missing-id behavior or related sub-resources.

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 already documents the key gotcha ('not the work order number'). The description adds no format or semantics beyond the schema, so 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?

States a specific verb+resource ('One work order with full detail') and enumerates the returned fields, which clearly separates it from list_work_orders. However, it never explicitly names the sibling it complements, so the distinction relies on the reader inferring singular-vs-list.

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 'GET /work_orders/{id}' hint implies retrieval-by-id usage, but there is no explicit when-to-use or when-not statement and no alternative tool named. Usage is inferable but not spelled out.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-derivable context: the Account-Token and permission flags are deliberately redacted from the response, which prevents an agent from chasing fields that will never appear. It stops short of documenting pagination behavior, but that lives in the schema.

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 units: a tight field list plus the endpoint. Nothing is padded and the most important fact (whose accounts, which fields) leads. It is a sentence fragment rather than a structured sentence, which is a minor stylistic weakness rather than a bloat problem.

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 correctly carries the return-value burden by naming the fields returned and, unusually, the fields withheld. Pagination is handled by the schema's cursor parameters, so the coverage is adequate for a 2-parameter read-only list 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 100% — both per_page and start_cursor are fully documented in the schema. The description says nothing about either parameter, so by the baseline rule this is a 3: the schema does all the work and the description neither adds nor detracts.

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 resource precisely (the Fleetio account(s) the API key belongs to) and enumerates the returned fields (id, name, address, plan, units, user type), and the 'GET /accounts' tag pins the endpoint. It is clearly distinguishable from every sibling, all of which operate on vehicles, contacts, work orders, etc. It loses a point only because it is phrased as a field inventory rather than a crisp verb-fronted purpose statement.

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 or when-not-to-use guidance, and no alternative is named (none exists among the siblings, but the description doesn't say so either). The scope phrase 'this API key belongs to' is a filtering constraint, not usage direction — it never tells the agent this is the bootstrap call for obtaining an account id.

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 this as a safe read (readOnlyHint=true, destructiveHint=false), so safety is covered structurally. The description adds genuinely useful non-annotation behavior: it returns exactly one page and paging is keyset-based, with next_cursor fed back as start_cursor. It does not cover rate limits or ordering defaults beyond what the schema states.

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 tight sentences, front-loaded with what the tool does and how to scope it, followed by endpoint and paging notes. No filler; every clause carries 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?

No output schema exists, so the description carries some return-shape burden; it partially covers this by noting a single-page, keyset-paged response. Combined with 100% schema coverage and read-only annotations, it is nearly complete, though the comment object's shape and default sort order are left unstated.

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, making 3 the baseline. The description adds light value by pairing commentable_type enum examples with commentable_id and by clarifying the next_cursor/start_cursor loop, but does not enrich beyond that.

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 ('List comments left on records') and immediately clarifies the scoping model (comments attached to a parent record via commentable_type + commentable_id). An agent can distinguish it from the write-side sibling fleetio_add_comment at a glance.

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 explains how to scope results ('Filter by the record') and how to page, which implies intended usage, but it names no alternative tools and gives no explicit when-not-to-use guidance. Adequate but leaves routing to the agent's 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-schema context: which fields are returned, the privacy guarantee that birth dates and driver-licence data are never returned, and the keyset-paging contract. It does not discuss permissions or rate limits.

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?

Front-loaded with what the tool is, then fields, then exclusions, then filters, endpoint, and paging in a tight sequence of sentences. No filler and no redundant restatement of the name or title.

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 carries the return-value burden and does so by listing returned fields, exclusions, and the next_cursor envelope. Paging and filtering are covered, but nothing is said about permissions/scopes or failure behavior, and the full set of filter dimensions (date bounds, employee_number) goes unmentioned.

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 every filter, sort field, date bound, and cursor. The description only restates a subset (email, last_name, group) and repeats the start_cursor rule already in the schema. Correct baseline for a fully documented 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 and resource ('List contacts') and immediately disambiguates the resource with concrete examples (drivers, technicians, employees). It also enumerates the returned fields, so the agent knows exactly what kind of record this returns versus the single-record get_contact sibling.

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 clear operational context: which fields can be used to filter (email, last name, group) and how to page ('pass next_cursor as start_cursor'). It stops short of naming get_contact as the alternative for retrieving a single contact, so there is no explicit when-not 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's main job is to add operational behavior — which it does by disclosing that results are keyset-paginated and returned one page at a time. It does not mention rate limits, filter semantics, or ordering guarantees, so it is good but not exhaustive.

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 with the resource definition and disambiguation front-loaded, followed by the endpoint and the paging contract. No filler, no restatement of the title.

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 13-parameter, all-optional list tool with no output schema, the description covers the essentials: what is listed, the endpoint, and the paging model including how to advance pages. It stops short of describing the shape of returned equipment records, which is the one gap given no output schema exists.

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 all 13 parameters are already documented in the schema. The description's only parameter-related statement — using next_cursor as start_cursor — restates what the start_cursor schema description already says, adding no new meaning. 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 and resource ('List equipment') and immediately disambiguates the resource as 'non-vehicle assets such as trailers and tools', which separates it from the large family of vehicle-list siblings. It also pins the underlying endpoint (GET /equipment). An agent can distinguish this from fleetio_list_vehicles 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?

The description gives pagination guidance ('pass next_cursor as start_cursor'), which is useful operational context, but never states when to prefer this over alternatives such as fleetio_get_equipment for a single asset or fleetio_list_vehicles for vehicles. Usage is implied by the resource name rather than spelled out, and none of the available filters are advertised.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: the response is a single page and continuation uses keyset paging by passing next_cursor as start_cursor. It stops short of stating auth requirements or rate limits.

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 what the tool returns, followed by the endpoint and the paging mechanics. No filler or 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?

For a read-only, 13-parameter paged list with no output schema, the definition covers purpose and the paging contract, which is the main thing an agent needs to iterate pages. It does not discuss how the numerous filters combine or what the page payload contains, a minor gap given the rich 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 100% across all 13 parameters, so the schema already documents code, name, sort_by, per_page, date bounds, and cursor semantics. The description only gestures at vehicle/code/last-occurrence and restates the cursor relationship already in the schema, adding little beyond 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?

States a specific verb (List) and resource (diagnostic trouble codes / faults) plus the source (telematics devices) and the returned fields (vehicle, code, last occurrence). This cleanly separates it from sibling list_* tools for vehicles, issues, work orders, etc.

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 resource name rather than stated: nothing says when to prefer this over fleetio_list_issues or fleetio_get_vehicle, and no filtering scenarios are suggested. The only operational guidance is the paging note, which is useful but not a when-to-use rule.

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 (readOnlyHint=true, destructiveHint=false), so the description earns credit for adding scope and mechanics: fuel-card data is explicitly excluded from results, and it discloses keyset pagination ('Returns one page... pass next_cursor as start_cursor'). It stops short of auth, rate-limit, or result-size details, but the pagination and data-exclusion notes are real additions.

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?

Four short sentences, front-loaded with the resource and payload, then filters, then the data-exclusion caveat and pagination rule. The raw 'GET /fuel_entries' line is marginal filler for an agent but is small; otherwise there is no wasted text.

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, 12-parameter list tool with no output schema, the description must carry return-shape and paging information, and it does: it enumerates returned fields and explains the one-page-plus-cursor loop. It does not cover default page size or empty-result behavior, but nothing essential to calling 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 description coverage is 100%, so all 12 parameters (sort_by, per_page, vendor_id, date/created_at/updated_at bounds, cursors) are already documented by the schema. The description's filter summary restates what the schema provides and adds no new param semantics, 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?

States a specific verb and resource ('List fuel purchases/fill-ups') and immediately enumerates the returned fields (vehicle, volume, price, total cost, efficiency), which distinguishes it from the many sibling list tools such as fleetio_list_meter_entries or fleetio_list_service_entries. An agent can identify this tool 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?

The description names the filter dimensions ('Filter by vehicle, vendor or date'), which implies when the tool is useful, but it never states when to prefer another tool or any prerequisite. Usage is inferable but not explicit, which is the definition of a minimum-viable 3.

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 read-only and non-destructive, so safety is covered. The description adds pagination behavior (returns one page, keyset paging, pass next_cursor as start_cursor) and the HTTP method, which is useful beyond 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?

Three compact clauses: lookup purpose, endpoint, paging instruction. No filler; front-loaded with the core action.

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?

Complete for a simple read-only list tool: annotations cover safety, schema covers parameters, and the description covers pagination. It could optionally mention that group IDs are used in other calls, but that is not essential.

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 all five parameters are well documented. The description restates the cursor mapping (next_cursor to start_cursor) but adds no new meaning 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?

States a specific verb (lookup) and resource (groups, clarified as locations/departments), plus the endpoint. However, it does not differentiate from the many sibling list_* tools; an agent must rely on the name and resource to pick it.

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?

No explicit when-to-use, when-not-to-use, or alternatives. The description implies a lookup but gives no context such as using it to resolve group IDs for filtering other resources.

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 (readOnlyHint, destructiveHint=false, openWorldHint). The description adds genuinely new behavioral context: it returns a single page and uses keyset paging where the prior reply's next_cursor is passed as start_cursor. That paging contract is not derivable from 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?

Three short sentences, front-loaded with purpose before the endpoint and paging detail. The raw "GET /inspection_forms" adds little for an agent but is compact and does not bloat the definition.

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 list tool with 100% schema coverage and strong annotations, the description is nearly complete: it covers what is listed and how paging works. Without an output schema it could say more about returned form fields, but that is a minor 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%, so the schema already documents all nine parameters, including the sort/enum and date-range fields. The description only echoes the paging relationship (next_cursor -> start_cursor), so the baseline of 3 is 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?

States a specific verb (List) and resource (inspection form templates) and clarifies the domain with a concrete example ("a daily DVIR"). This distinguishes it from the singular sibling fleetio_get_inspection_form, though it never names that sibling 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?

Usage is implied by the plural "List" verb and the paging note, but the description gives no explicit when-to-use guidance or exclusions relative to siblings like fleetio_list_submitted_inspections or fleetio_get_inspection_form. An agent must infer the context.

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, openWorldHint, and destructiveHint, so safety is covered. The description adds useful behavioral detail about keyset paging and the next_cursor/start_cursor relationship that annotations cannot convey.

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 short and front-loads purpose, use case, endpoint, and paging behavior. Minor redundancy in restating the GET endpoint, but no wasted sentences.

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 adequately explains that it returns issue priorities, their ids, and one page with a continuation cursor. It could specify returned fields more, but is sufficient for a lookup 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 coverage is 100%, so all five parameters are fully documented. The description's paging note largely restates what the start_cursor schema already says, adding no syntax or format detail beyond the structured data.

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 ('Lookup') and resource ('issue priorities and their ids') and adds a concrete purpose (needed to create an issue with a priority). It does not explicitly differentiate from the many sibling list_* tools, but the resource specificity makes selection unambiguous.

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 'needed to create an issue with a priority' gives a clear use context, telling the agent when this tool is the right lookup. It lacks explicit exclusions or named alternatives among the sibling list tools, keeping it from 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 declare readOnly/openWorld/non-destructive, so the bar is lower, yet the description adds genuinely useful behavior: it states it returns one page and explains keyset paging ('pass next_cursor as start_cursor'). It omits default page size and rate/auth details, but this is solid added 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?

Four tight sentences, front-loaded with purpose, then filters, then endpoint, then paging. No filler; dense but every sentence conveys something actionable.

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 17-param read tool with no output schema, the description covers purpose, filters, and pagination semantics, and hints at returned fields (state, priority, assignees, due date). Defaults and the full return shape are left to the schema, which is reasonable.

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 all 17 params are self-documented, establishing a baseline of 3. The description surfaces the primary filter set (state, vehicle, equipment, reporter) but does not explain the date-range filters, sort_by/sort_direction interplay, or number, so it adds only marginal meaning.

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?

Specific verb+resource ('List issues') with a helpful domain gloss ('defects and problems reported against vehicles and equipment'). It is distinguishable from fleetio_get_issue and fleetio_create_issue, but it never names those siblings to actively route the agent.

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?

Filter dimensions are listed ('Filter by state, vehicle, equipment or reporter'), which implies usage context, but there is no explicit when-to-use-this-vs-alternatives guidance or exclusions (e.g., use get_issue for a single issue).

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/not-destructive/open-world, so the safety profile is covered. The description then adds genuinely non-annotation behavior: it returns exactly one page, uses keyset paging, and the next_cursor from the prior reply must be passed as start_cursor — actionable context an agent cannot get from 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 compact sentences, resource and scope front-loaded, then endpoint and paging caveat. No filler text; arguably the 'GET /labels' fragment adds little for an agent but costs only three tokens.

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-required-param list tool with full schema coverage, safe annotations and no output schema, the description covers what the agent needs: what is listed, paging mechanics, and the cursor handoff. Return item fields are not described, but paging behavior is the main risk here and it is addressed.

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 name, sort_by, per_page, start_cursor and sort_direction, making 3 the baseline. The description's only added parameter meaning is the next_cursor→start_cursor handoff, which the start_cursor schema description already states, so it adds little beyond duplication.

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 resource (labels/tags) and scopes it to the entity types it applies to (vehicles, issues, work orders, service entries), plus the endpoint GET /labels. It is distinguishable from siblings like fleetio_list_groups or fleetio_list_vehicle_statuses, though the leading word 'Lookup' slightly understates that this is a paginated list operation.

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?

No explicit when-to-use or when-not-to-use guidance and no named alternative among the ~40 sibling list tools. The cross-entity scope note ('used on vehicles, issues, work orders and service entries') implies the agent should call this when it needs the shared tag vocabulary, which is weak but non-zero 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?

Annotations already declare the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so safety is covered. The description adds genuinely useful behavioral context beyond that: it discloses the endpoint, that results are returned one page at a time, and the keyset paging convention ('pass next_cursor as start_cursor'). It omits default page size and rate limits, but this is solid added value.

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 tight sentences, front-loaded with the purpose, followed by filters and the paging caveat. Each sentence carries distinct information with no filler, though the endpoint string is mildly redundant.

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 list tool the safety profile is covered by annotations, and paging behavior is disclosed. However, with no output schema, the description only says 'Returns one page' and does not characterize the returned meter-entry shape, leaving a gap for an agent assembling results across pages.

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% with all 8 params documented, so the schema does the heavy lifting. The description only mentions vehicle and date filtering, which the schema already covers with more precision (ISO 8601 patterns, bounds). Baseline 3 is 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?

States a specific verb and resource ('List meter readings') and scopes it to 'across the account', which usefully implies a wider scope than the vehicle-scoped sibling fleetio_list_vehicle_meter_entries. It stops short of explicitly contrasting with that sibling, so it's 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?

It names the practical filters ('Filter by vehicle and by date'), which implies typical usage, but gives no explicit when-to-use vs when-not guidance and does not route the agent to fleetio_list_vehicle_meter_entries for vehicle-scoped reads. Usage is only 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds behavior beyond that: it returns exactly one page and uses keyset paging where the previous reply's next_cursor is passed as start_cursor. It does not mention rate limits or auth requirements, so it is strong but not exhaustive.

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?

Four short clauses, front-loaded with the resource and its returned fields, then filters, then endpoint and paging. Every sentence carries distinct information with no filler or restated title.

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 compensates by naming the returned fields and explaining the one-page/keyset paging model, which is the main thing an agent needs to iterate correctly. It leaves filter date-range semantics and sort interactions to the schema, which is acceptable given 100% schema coverage.

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 the baseline is 3; the schema already documents all 12 parameters including format patterns and enum values. The description adds value by mapping the API-level next_cursor to the start_cursor input and by confirming which fields are filterable, which is cross-field information the schema alone does not convey.

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 (list parts, qualified as the 'inventory catalog'), and enumerates the returned fields (part number, manufacturer number, category, unit cost), which implicitly separates it from fleetio_list_part_stock and fleetio_get_part. It never names a sibling alternative explicitly, so it falls short of full sibling 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?

The description hints at usage by naming the filterable fields (part number, manufacturer part number, UPC), implying when to use each filter. However, it gives no when-to-use guidance relative to alternatives such as fleetio_get_part for a single record or fleetio_list_part_stock for stock levels, and lists no exclusions or prerequisites.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context: it returns a single page, uses keyset paging, and that the next_cursor must be passed back as start_cursor — the kind of information the annotations cannot express.

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, front-loaded sentences: purpose first, filters second, paging behavior last. No filler and no repetition of annotation-provided facts.

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 usefully states the shape of the result (quantity per location, one page) and how to page, and all parameters are schema-documented. It could go slightly further on pagination termination or result ordering, but nothing essential is missing for correct 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?

Schema description coverage is 100%, so all six parameters are already documented, including sort fields, per_page bounds, and cursor semantics. The description restates the two filter parameters and the cursor round-trip without adding format or default details beyond the schema, 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?

States a specific verb and resource ('List on-hand inventory of parts per part location') with clarifying scope ('quantity by location') and the underlying endpoint. This clearly separates it from sibling list tools such as fleetio_list_parts, which enumerate part definitions rather than stock levels.

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 says what can be filtered ('Filter by part or part location'), which implies usage, but never states when to pick this tool over fleetio_list_parts or fleetio_get_part, nor any prerequisites for part_id/part_location_id. Usage is inferable rather than explicit.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-structured behavior: the call returns exactly one page and is keyset-paged via next_cursor -> start_cursor, which is the key operational trait an agent 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?

Three short, front-loaded sentences: identity and returned fields first, endpoint second, paging contract last. No filler or restatement of the title.

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 compensates by naming the paging mechanism and the kind of data returned (address, coordinates, radius). Filtering/sorting parameters are left entirely to the schema, which is acceptable given full schema coverage, but the response envelope is only partially described.

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 goes beyond the schema by linking the start_cursor parameter to the response's next_cursor field, clarifying the paging contract in a way the schema alone does not, but it adds nothing about name/sort_by/per_page semantics.

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 ('List places') and immediately disambiguates the domain term with '(geofences/locations)'. The mention of returned fields (address, coordinates, radius) and the underlying endpoint GET /places makes the scope unambiguous against the many other fleetio_list_* 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 explains how to page ('pass next_cursor as start_cursor') but never states when to use this tool versus an alternative, nor any prerequisites (e.g., permissions or when places are relevant vs vehicle/contact lookups). Usage is implied rather than guided; given no true sibling overlap for listing places, this is adequate but thin.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the call returns exactly one page and uses keyset paging where next_cursor from the prior reply is passed as start_cursor. It stops short of stating default page size or how to detect the final page, but the paging contract is the key operational detail and it is disclosed.

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 dense sentences, front-loaded with what the tool returns before the filtering, endpoint and paging notes. Nothing is padded, though the bare 'GET /service_entries' is close to redundant and the paging sentence could be tighter.

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 carry the burden of describing returns and does so at a useful level (vehicle, vendor, dates, notes) plus the one-page/keyset pagination model. The remaining gap is that it names only two of the several supported filter families, which could lead an agent to miss created_at/updated_at or sort options, but the essentials for correct invocation are present.

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 11 parameters with bounds, enums and ISO 8601 patterns; baseline 3 applies. The description adds the cursor round-trip semantics (next_cursor -> start_cursor) but otherwise only gestures at filters, and its 'reference or completion date' framing understates the created_at/updated_at and sort parameters the schema exposes.

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 (service entries), and helpfully glosses the resource as 'completed maintenance records' with the fields carried (vehicle, vendor, dates, notes). It does not differentiate from close siblings such as fleetio_list_vehicle_service_entries (scoped to one vehicle) or fleetio_get_service_entry (single record), so an agent must infer the distinction itself.

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?

Filtering guidance is present ('Filter by reference or completion date') and the paging workflow is spelled out, which implies when to use it for bulk retrieval. There is no explicit when-to-use statement versus the vehicle-scoped sibling list or the single-record getter, and no note about the other available date filters, so usage is only 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about what is returned (tasks, parts, labor) and confirms the HTTP GET operation, but it does not disclose pagination behavior despite per_page and start_cursor parameters.

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 very short and front-loads the resource being returned. The second sentence is an API endpoint duplication that adds little for an agent already seeing the tool name, but it is not verbose or poorly structured.

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 list tool with 100% schema coverage and annotations covering safety, the description gives enough context: what line items are and that they belong to one service entry. It omits pagination details and sibling alternatives, but those are minor gaps.

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 all parameters are already documented in the schema. The description only implies that service_entry_id is singular and required via 'ONE service entry,' adding minimal semantic detail beyond the structured fields.

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 clear resource (line items: tasks, parts, labor) and scopes it to ONE service entry, which distinguishes it from list_service_entries and get_service_entry. However, it does not explicitly differentiate from similar sibling list tools such as list_work_order_line_items.

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 'of ONE service entry' implies the tool is used when line items for a specific service entry are needed, but there is no explicit when-to-use guidance or named alternative. The endpoint notation gives implied context without routing the agent away from siblings.

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 (readOnlyHint true, destructiveHint false, openWorldHint true), so the bar is lower. The description still adds valuable non-annotation behavior: the response is a single page and paging is keyset-based, with next_cursor passed as start_cursor on the next 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?

Three tightly packed sentences front-load purpose, then filters, then endpoint and paging. Every clause carries information and nothing is padded.

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 7 optional parameters, no output schema, and simple paging, the description supplies what an agent needs: what is returned, the endpoint, and exactly how to page. Output field detail is unnecessary without a return 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 100%, so the schema already documents every parameter, including the status enum values the description repeats. The description adds only filter intent (what can be filtered) but no syntax or format detail beyond the schema, matching the baseline 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?

States a specific verb and resource ('List preventive-maintenance service reminders') plus what it returns (next-due dates, meter values). This cleanly separates it from sibling list tools such as fleetio_list_service_tasks and fleetio_list_service_entries, which cover different resources.

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 states the applicable filters (status, vehicle, service task) and the GET endpoint, which implies when it is useful, but it never names or excludes alternatives such as fleetio_list_vehicle_renewal_reminders or fleetio_list_service_tasks. Usage context is implied rather than routed.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: it names the underlying GET /service_tasks call, states that only one page is returned, and explains the keyset paging mechanism. It still omits default page contents/ordering nuances, but this is solid added value.

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 tool's identity and purpose, with no filler. It is efficient, though the endpoint path is arguably redundant for an agent that never invokes raw HTTP.

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 endpoint with no output schema, the description conveys purpose, pagination behavior, and scope sufficiently. The main omissions are return-field detail and explicit sibling routing, which are minor given annotations and the 100%-covered 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 100%, so all five parameters (filter, sort, per_page, cursor, direction) are already documented in the schema. The description's only parameter-related note, mapping next_cursor to start_cursor, largely restates what the schema's start_cursor field says. Baseline 3 is appropriate when the schema carries the semantics.

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 clear verb+resource ('Lookup: the service tasks ... and their ids') with concrete examples (Oil Change, Tire Rotation) that clarify what a service task is versus a service entry. It does not explicitly differentiate from siblings like fleetio_list_service_entries, but the resource is specific enough that an agent can distinguish a catalog lookup from transaction listings.

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 by the word 'Lookup' and the endpoint path; there is no statement of when to prefer this tool over fleetio_list_service_entries or the work-order/service-reminder siblings. It does give practical pagination handling guidance (pass next_cursor as start_cursor), which is a genuine usage 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?

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: it returns exactly one page and uses keyset paging where next_cursor is fed back as start_cursor. It omits rate limits and error behavior, but for a read list tool this is solid.

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 purpose, then endpoint, then paging. Every sentence earns its place; the endpoint path is mildly redundant but the paging sentence is essential and not 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?

With no output schema, the description correctly compensates by naming the returned fields (vehicle, driver, failed item count, submit time) and explains pagination. Filter surface is fully documented in the schema. Nothing critical is missing, though edge cases like empty pages or cursor expiry are 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 100% across all 13 parameters, including ranges, enums and ISO-8601 patterns, so the schema carries the load. The description adds only the paging semantics (start_cursor from next_cursor) and the underlying endpoint path, which is marginal extra value. 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?

States a specific verb (List) and resource (submitted inspections), and clarifies the resource as 'filled-in forms', which usefully distinguishes it from fleetio_list_inspection_forms (form templates) and fleetio_get_submitted_inspection (single record). It also enumerates returned fields. It does not name sibling tools explicitly, 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?

Usage is implied by the list/filter shape and the paging note ('pass next_cursor as start_cursor'), which tells the agent how to walk pages. However, there is no explicit when-to-use versus fleetio_get_submitted_inspection or fleetio_list_inspection_forms, and no stated preconditions.

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/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the underlying GET /vehicle_assignments endpoint and the keyset pagination contract (one page returned, pass next_cursor as start_cursor). It stops short of rate limits or auth details.

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 compact, front-loaded fragments — purpose, endpoint, pagination — with zero filler. Each sentence adds distinct information and the core function leads.

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 usefully explains the paging contract, which is the main risk of misuse for a list endpoint. It could go further by sketching the returned assignment fields, but for a 10-param filter/list tool with full schema coverage it is sufficiently 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by bridging the output field 'next_cursor' to the input 'start_cursor', which the schema alone does not. It also maps 'vehicle or contact' filtering onto vehicle_id/contact_id.

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 with semantic clarification: 'List which driver (contact) was assigned to which vehicle and when'. The driver=contact equivalence and the assignment relationship are made explicit, letting an agent distinguish this from fleetio_list_vehicles and the other list_* 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?

Gives clear filtering context ('filter by vehicle or contact'), which routes the agent to the relevant parameters. It does not name alternatives or state when-not to use it, but no sibling tool lists assignments, so the guidance bar is effectively met without exclusions.

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 carry the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real behavior: the response is a single page, the ordering is newest-first by default, and the keyset cursor is threaded via next_cursor -> start_cursor. Note the 'newest first' claim sits oddly against the schema's 'sort_direction default asc', but that is a schema tension, not an annotation contradiction.

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 tight sentences: scope first, endpoint second, paging contract last. Every sentence carries information an agent needs and there is no 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?

For an 8-parameter list tool with full schema coverage and no output schema, the description supplies the scoping rule, the default ordering, and the paging contract, which is enough to drive a correct call loop. It does not spell out response shape details (totals, empty results), but that gap is minor here.

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 every one of the 8 parameters is already documented in structured form, establishing the baseline of 3. The description's cursor chaining note restates what start_cursor's own schema description already says, adding little beyond that.

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 ('List the odometer / engine-hour meter readings') and scopes it hard to a single vehicle, which implicitly separates it from the account-wide fleetio_list_meter_entries. It stops short of naming that sibling or the create counterpart explicitly, so differentiation is inferred rather than stated.

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 context is implied by the defaults and the paging loop instruction ('pass next_cursor as start_cursor'), which tells the agent how to continue. There is no explicit when-to-use-this-vs-alternatives guidance, and no exclusions or prerequisites (e.g. required permissions, behavior when the vehicle has no entries).

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real behavioral context beyond that: results are paginated one page at a time and continuation is via next_cursor passed as start_cursor. It does not describe rate limits or the shape of returned records, but the paging contract is the key behavior an agent 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?

Three compact sentences with the purpose, filter scope, endpoint, and paging contract front-loaded and no filler. Every sentence contributes information the 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?

With no output schema, the description carries the return-behavior burden and does so at a basic level ('Returns one page'). Combined with full schema coverage and read-only annotations, this is sufficient to invoke correctly, though a hint about what each reminder record contains would make it 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?

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the cursor round-trip ('pass next_cursor as start_cursor') and identifying vehicle/status as the primary filter dimensions, which the schema does not spell out as a workflow.

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 ('List vehicle renewal reminders') and clarifies the domain with the parenthetical '(registration, insurance, inspections due)', which separates it from sibling tools like fleetio_list_service_reminders. It stops short of naming an alternative sibling explicitly, so differentiation is implied rather than stated.

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?

'Filter by vehicle or status' implies when the tool is useful, and the paging sentence gives a clear continuation rule. However, there is no explicit when-to-use guidance versus list_service_reminders or list_vehicles, and no stated prerequisites or exclusions.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real behavioral context beyond them: archived records are excluded, the call returns a single page, and paging is keyset-based via next_cursor/start_cursor. It stops short of describing rate limits or ordering defaults.

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 dense sentences, front-loaded with purpose and scope, then filtering/routing, then transport and paging. No filler and nothing repeated from annotations or schema.

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 14-parameter, no-output-schema list tool, the description covers scope, filters, id sourcing, endpoint and paging, which is what an agent needs to call it correctly. Minor gaps remain around sort defaults and response envelope shape, but nothing essential 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 the baseline is 3; the description earns an extra point by explaining the non-obvious provenance of three integer id filters (group_id, vehicle_type_id, vehicle_status_id) from named lookup tools and by restating the cursor/next_cursor contract. It does not cover sort_by/sort_direction interaction explicitly, which the schema already documents.

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 ('List vehicles') plus a key scope constraint ('not archived') and enumerates the fields returned (status, type, group, meter readings, VIN, plate). An agent can distinguish it from fleetio_get_vehicle and from sibling list_* tools without opening any 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 names the filterable dimensions and routes the agent to the correct sibling tools for the required ids (fleetio_list_vehicle_statuses, fleetio_list_vehicle_types, fleetio_list_groups), which is genuine routing guidance. It does not state when NOT to use this tool (e.g. use fleetio_get_vehicle for a single known id), so it falls short of the 5 bar.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it returns exactly ONE page and uses keyset paging via next_cursor, which governs how the agent must iterate. Auth needs and rate limits remain unstated.

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 terse sentences, front-loaded with the scope constraint, followed by the endpoint and the paging rule. No filler and every sentence carries information the 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 read-only list tool with no output schema, the description covers scope, filtering locality and pagination adequately. It stops short of describing the shape of a returned service entry, but with eight fully documented schema parameters the remaining gap is minor.

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 every parameter (sort_by, per_page, reference, cursors, date bounds) is already documented in the schema. The description only restates the cursor parameter mapping, adding little beyond what the schema provides; 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?

States a specific verb and resource ('List the service entries') plus an explicit scope constraint ('of ONE vehicle'), which distinguishes it from the account-wide sibling fleetio_list_service_entries. The REST endpoint is included, leaving no ambiguity about what is retrieved.

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 vehicle-scoped wording and the pagination instruction ('pass next_cursor as start_cursor') gives concrete procedural guidance. However, no alternative is named and no condition is stated for choosing this tool over fleetio_list_service_entries or fleetio_list_service_entry_line_items.

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 establish read-only/non-destructive/open-world, so safety is covered. The description adds value beyond them by disclosing the paging model ('Returns one page (keyset paging: pass next_cursor as start_cursor)') and the underlying endpoint, which an agent needs to page correctly.

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 compact fragments: purpose, endpoint, and paging behavior. Zero filler, and the most decision-relevant information (what the statuses are and why to fetch them) comes first.

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 carries return-shape burden and does so adequately: one page plus the next_cursor contract. Safety profile is handled by annotations. Minor gap is the absence of any note on rate limits or how many statuses typically exist.

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 each of the five params is documented there, so this is the baseline case. The description's cursor note largely restates the schema's start_cursor text rather than adding new syntax or constraints.

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+resource ('Lookup: the vehicle statuses...and their ids') and gives concrete example values (Active, In Shop, Out of Service), which separates it cleanly from siblings like fleetio_list_work_order_statuses and fleetio_list_vehicle_types. The purpose for the caller ('for filtering vehicles') is explicit.

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 clearly frames when to reach for this tool: when you need status ids to filter vehicles by status. It does not name alternatives or state when-not to use it, but the use case is unambiguous enough that an agent can place it.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it is a GET /vehicle_types call, returns exactly one page, and is keyset-paginated with next_cursor passed back as start_cursor. It still doesn't say whether a total count or filter feedback is returned.

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 resource and its ids, then the endpoint, then the paging rule. Nothing is padded and no sentence fails to carry 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?

With no output schema, the description compensates by naming the response shape essentials (a single page) and the cursor key (next_cursor). It would be fully complete if it noted that no pagination metadata beyond the cursor is available, but it is adequate for a 5-param read-only list.

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 every parameter (name, sort_by, per_page, start_cursor, sort_direction) is already documented, including the next_cursor-to-start_cursor relationship. The description's paging note largely repeats the schema rather than adding syntax or format detail, so the baseline of 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?

Specific verb (lookup/list) plus resource (vehicle types) with concrete examples (Car, Truck, Van) and the id payload, so an agent can tell it apart from list_vehicles or list_vehicle_statuses. It never names a sibling explicitly, so it falls short of full sibling 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?

Usage is only implied: the tool is a reference lookup whose value is resolving type ids/names. There is no statement about when to prefer this over fleetio_list_vehicles or how the returned ids should be consumed elsewhere.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: this is a keyset-paginated endpoint returning exactly one page, with the cursor from the previous reply fed back as start_cursor. It stops short of describing the returned payload, which matters since there is no output schema.

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 purpose, then endpoint, then the paging behavior. Every clause carries information; the only marginally redundant element is 'GET /vendors', which is harmless and cheap.

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 10-parameter, all-optional read endpoint with full schema documentation and no output schema, the description covers purpose, scope and pagination adequately. It could be slightly stronger by mentioning that results are filterable by name/external_id/date ranges or what a vendor record contains, but 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?

Schema description coverage is 100%, so the baseline would be 3 and the schema carries filter/enum/paging semantics on its own. The description earns an extra point by clarifying the start_cursor round-trip contract with next_cursor, which the schema only hints at ('omit for the first page').

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 ('List vendors') and disambiguates the domain by naming what a vendor is (repair shops, fuel stations, parts suppliers). Combined with the sibling naming convention (fleetio_get_vendor), an agent can tell list-from-get without opening a 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?

The description says the call returns one page and how to continue via next_cursor/start_cursor, which is useful operational guidance. However, it never states when to prefer this over fleetio_get_vendor or fleetio_list_places, nor any exclusions or prerequisites, so usage is only 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, and the description's 'GET /work_orders/{id}/work_order_line_items' merely restates that it is a read. It adds modest value by naming what the line items contain (labor, parts, fees) and emphasizing single-parent scoping, but discloses no pagination or auth behavior beyond what the schema already documents.

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 zero filler, and the resource scope is front-loaded ahead of the HTTP endpoint. It is efficient, though the extreme brevity leaves it thin for a tool with a required parent id.

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?

A simple read-only list tool with no output schema, and pagination is fully covered by the schema descriptions. However, without an output schema the description gives no sense of the returned line-item fields (rates, quantities, totals), leaving an agent guessing about the 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 work_order_id, per_page (2-100, default 25), and start_cursor are all fully documented in the schema. The description only reinforces that work_order_id is required and singular; baseline 3 is 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?

States a specific resource (line items) with its parent scope emphasized ('of ONE work order') and enumerates the content types (labor, parts, fees). This distinguishes it from the sibling fleetio_list_service_entry_line_items, which covers a different parent resource, though the verb 'list' is only implied by the 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?

No guidance on when to use this versus alternatives such as fleetio_get_work_order or fleetio_list_work_orders. The 'ONE work order' phrasing implies the parent must be known first, but nothing is stated about prerequisites or when-not-to-use.

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 destructiveHint=false, so safety is covered. The description adds genuine non-annotated context: keyset paging ('Returns one page (keyset paging: pass next_cursor as start_cursor)') and the domain relationship that a finished work order produces a service entry. It stops short of richer operational detail like rate limits or auth scopes.

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?

Four short sentences, each carrying distinct information (purpose, filters, domain relationship, endpoint/paging), with the core purpose front-loaded. It is efficient, though the 'GET /work_orders' fragment adds little for an agent that already has the tool name.

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 and 15 parameters, the description compensates reasonably by naming the returned entities and explaining the keyset pagination contract. It is nearly complete for a filtered list tool, though it omits anything about response size limits beyond per_page and default ordering specifics.

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 15 parameters including the sort enum and ISO-8601 date filters. The description merely restates a subset of the filters (vehicle, vendor, technician, number, status name) without adding syntax or format guidance, matching the baseline-3 case where 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?

The description opens with a specific verb+resource ('List work orders') and disambiguates the domain term with the parenthetical '(shop jobs)'. It also enumerates the attributes returned (status, vehicle, vendor, technician), which cleanly separates it from the single-record sibling fleetio_get_work_order and the related fleetio_list_work_order_line_items.

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 names the filterable dimensions and gives a status example ('Open'), which implies when the tool is useful, but it never states when to prefer it over alternatives (e.g. fleetio_list_work_order_statuses to discover valid status names) or any exclusions. Usage is implied rather than spelled out, so this is minimum-viable 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?

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds genuine value beyond that by disclosing the read endpoint (GET /work_order_statuses) and, importantly, that results are keyset-paginated one page at a time and that next_cursor must be fed back as start_cursor. It does not describe rate limits or auth needs, but the paging contract is the key behavioral detail.

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, zero filler, with purpose first and the paging mechanics last. The 'Lookup:' lead-in is slightly terse/telegraphic but nothing 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 an unauthenticated-parameterless list tool with no output schema, the description tells the agent what it returns (one page of statuses) and how to iterate pages. It could go further by sketching the shape of a status record (id, name, color) since no output schema exists, but the essentials are present.

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 all five parameters are already documented, including the start_cursor == previous next_cursor relationship. The description only restates the cursor chaining, adding little beyond the schema; baseline 3 is 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?

Names a specific verb (lookup/list) and resource (work order statuses) and even enumerates sample values (Open, In Progress, Completed), so an agent immediately knows this returns the status reference set. It is distinguishable from fleetio_list_vehicle_statuses by resource name, though it never explicitly contrasts with 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?

No statement of when to call this versus siblings such as fleetio_list_work_orders or fleetio_get_work_order, and no mention that this is typically used to resolve valid status IDs/names for filtering work orders. Usage is only faintly implied by the word 'Lookup'.

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