FieldPulse MCP by usefulapi

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

The description reinforces the annotations by marking this as a WRITE and warning that it creates a new record every call, which clarifies the non-idempotent and duplicate-risk behavior. It adds useful context beyond the annotations, though it does not discuss permissions, side effects beyond creation, or response behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the WRITE marker and core action, and every sentence adds practical value: identity requirement, duplicate caution, and endpoint. There is no wasted prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 28-parameter create tool with low schema description coverage and no output schema, the description covers the essential identity rule and duplicate warning but omits many optional field semantics and does not mention what the create operation returns. It is adequate for basic invocation but incomplete for fully informed use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 28 parameters and only 25% schema description coverage, the description does important work by stating that first_name and/or last_name or a unique display_name are needed. However, it leaves most of the large parameter surface unexplained, including status/account_type semantics and many address/contact 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 uses a specific verb and resource: create a customer, explicitly scoped to lead or account records. It also distinguishes the action from listing by directing duplicate checks to fieldpulse_list_customers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage guidance by saying to check fieldpulse_list_customers first to avoid duplicates. It does not explicitly say to use fieldpulse_update_customer when a matching customer already exists, so the alternative path 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 write, destructive, non-idempotent and open-world, so the safety profile is covered. The description earns credit beyond that by spelling out the concrete consequence of non-idempotency ("Creates a new job every call"), which warns the agent against retry loops creating duplicates, and by prefixing "WRITE:" and the POST endpoint. It does not describe permissions or the response body.

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?

Roughly three compressed clauses with the write-scope flag front-loaded first, then required fields, then the status choice, then the non-idempotency warning. Every sentence carries information and 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 a 17-parameter creation tool the description covers the three required fields and the trickiest decision (which status mechanism to use), and annotations supply the mutation profile. The only real gap is that with no output schema it never says what comes back (e.g. the new job id), which an agent may need to chain 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 coverage is 71%, so the schema already explains most parameters, including the full status enum meanings and the status_id/status_workflow_id pairing. The description restates the three required parameters and the "numeric billing value" quirk but adds no format or constraint detail beyond 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?

States a specific verb and resource ("create a job for an existing customer") and names the API endpoint (POST /jobs), so it is unambiguously a creation tool distinct from fieldpulse_update_job, fieldpulse_get_job and fieldpulse_list_jobs. It stops short of explicitly naming any sibling, so it does not reach 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?

"For an existing customer" implies the prerequisite that the customer must already exist, and the status clause gives a usable either/or rule (status 1-6 versus status_id + status_workflow_id). But it never says when to prefer this over fieldpulse_update_job, nor what to do before creating (e.g. create the customer first); usage context 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 safety is covered. The description adds nothing beyond the HTTP path — no note on what happens when the id does not exist, whether the response is a single object or enveloped, or any auth/permission context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short fragments, zero padding, and the key qualifier ('one asset') is front-loaded. It is arguably over-trimmed, but no sentence is wasteful.

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 with full schema coverage and annotations, the essentials are present. However, with no output schema, the description gives no hint about return shape (asset object fields) or not-found behavior, leaving a modest 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 coverage is 100% and the single asset_id parameter is documented in the schema with type and constraint. The phrase 'by id' restates the schema rather than adding format or lookup semantics, 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 the verb+resource precisely (fetch a single asset by its id) and the underlying endpoint, which implicitly distinguishes it from fieldpulse_list_assets. It does not name the sibling list tool 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?

There is no guidance on when to use this versus fieldpulse_list_assets or fieldpulse_list_asset_categories, and no prerequisites or error conditions mentioned. The agent must infer that an id is required and that listing is a separate 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 adds only the REST path, with no note on not-found behavior, permissions, or what a returned contract contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short fragments, front-loaded with the essential fact and no filler. It borders on under-specification, but nothing present is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with annotations and no output schema, the description is minimally sufficient to invoke it. It nonetheless omits return shape and error semantics, leaving the agent to discover the response structure at call time.

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 the single contract_id parameter is already documented as "FieldPulse contract id" with type and range constraints. "by id" in the description adds nothing 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?

"One contract by id" states the specific verb (fetch single) and resource, and the singular framing implicitly distinguishes it from fieldpulse_list_contracts. It is terse but an agent can tell what it retrieves 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?

There is no guidance on when to use this versus fieldpulse_list_contracts, no mention of prerequisites, and no note about what happens when an id does not resolve. The agent must infer the selection rule entirely.

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 description needn't restate safety. It adds only the REST path, with no mention of what happens on a missing id (404/error) or what the returned object contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the resource and scope. Nothing is wasted, though the endpoint fragment borders on redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with full annotation coverage and no output schema, this is minimally viable. It never tells the agent what a customer record includes or how errors surface, leaving the caller to infer behavior.

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 customer_id parameter is documented as a positive FieldPulse customer id. The description adds nothing 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: fetch one customer by id, which implicitly distinguishes it from the sibling list_customers and other get_* entity tools. It is terse but 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?

No guidance on when to use this rather than fieldpulse_list_customers or fieldpulse_get_customer_contact, and no note that the id must be an existing customer. The only implied usage is 'you already have an 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds only the REST path, which is structural rather than behavioral; it says nothing about auth, error behavior (e.g., missing contact), or what a contact record contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded, with no filler. There is minor redundancy between the 'one contact of a customer' fragment and the endpoint path, which both convey the same resource, but overall it is tight.

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 two-param read tool with full schema coverage and annotations, the essentials are present. However, with no output schema, the description never indicates what fields a contact returns, so an agent cannot anticipate the response shape from the definition alone.

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 both customer_id and contact_id are already documented with their meanings and constraints. The endpoint path mirrors the two parameters but adds no syntax, format, or sourcing guidance beyond what the schema provides, warranting 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?

The description names the resource (a single customer contact) and the backing endpoint, which combined with the verb in the name tells an agent this is a single-record fetch. The singular framing implicitly distinguishes it from the list_customer_contacts sibling, but the first sentence ('One contact of a customer') leans heavily on the tool name rather than adding independent detail.

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 statement of when to use this tool rather than fieldpulse_list_customer_contacts or fieldpulse_get_customer. The agent is left to infer from the singular/plural naming that this retrieves one record by id, with no explicit routing 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 safety is fully covered. The description adds only the REST path 'GET /estimates/{id}', which merely restates the read semantics, and says nothing about behavior on a missing/invalid id or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short fragments with zero waste and the key information front-loaded. The telegraphic style borders on under-specification rather than excess, so it is efficient but not exemplary.

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 single-parameter read tool whose annotations carry the safety profile and whose schema fully documents the input. However, with no output schema, the description could usefully say what an estimate response includes and what happens when the id does not 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 coverage is 100% and the single parameter 'estimate_id' is documented with type, bounds, and a description. The description's 'by id' adds nothing 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 resource and scope ('One estimate by id'), which implicitly distinguishes it from the sibling 'fieldpulse_list_estimates'. It is a fragment rather than a verb-led sentence, but an agent can tell it retrieves a single estimate rather than a collection.

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 fieldpulse_list_estimates or any other sibling, and no stated preconditions (e.g., the id must already be known). The 'by id' phrasing is the only implied routing cue.

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 REST mapping (GET /invoices/{id}), which is mildly useful context but discloses nothing about error behavior, missing records, or payload size. Adequate, not rich.

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 fragments, front-loaded with the resource and zero filler. It is arguably under-specified rather than padded, but every word present 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 simple single-entity read this is serviceable: annotations cover safety and the schema covers the sole parameter. However, there is no output schema and the description says nothing about the returned invoice shape or not-found behavior, leaving a real gap for an agent planning a call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With one parameter and 100% schema description coverage, the schema already defines invoice_id with type, bounds and semantics. The description's 'by id' is consistent but adds no new meaning beyond that 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 precisely what is returned (a single invoice) and the selector (by id), which implicitly separates it from the sibling fieldpulse_list_invoices. It stops just short of an explicit verb phrase like 'retrieve one invoice', so it is clear but not maximally polished.

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, no mention of the list alternative for browsing, and no guidance on what happens when the id does not exist. The 'by id' phrasing only weakly implies the usage condition.

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 only the raw endpoint path (GET /items/{id}), with no note on error behavior for missing ids, permissions, 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 short sentences, zero padding, and the core operation is front-loaded. It is terse to the point of under-specification, 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 a single-parameter read tool whose annotations and schema are fully covered, the description is minimally sufficient. It leaves an agent without any statement about return content or lookup semantics beyond the endpoint string.

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 item_id is already documented as a positive integer FieldPulse item id. The description adds nothing 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?

"One invoice item by id" states the verb (retrieve one) and the resource (item), which cleanly distinguishes it from the sibling list_items. The qualifier "invoice" is slightly ambiguous — FieldPulse items are reusable price-book entries — but the intent is still 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?

No guidance on when to use this versus fieldpulse_list_items or whether the item must already exist. The agent must infer that this is the single-record lookup path from the tool 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 fully covered structurally. The description adds only the REST endpoint (GET /jobs/{id}) and the fact that custom fields are opt-in; it says nothing about return shape, not-found behavior, or auth requirements. With annotations carrying the main burden, this is adequate but thin.

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 clauses, front-loaded with the core action; the endpoint fragment is the only arguably redundant element and it is minimal. No padding or hedging.

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 two-parameter read tool with full schema coverage and complete annotations, this is close to sufficient: it conveys the resource, the optional expansion, and a return hint ('One job'). The only gap is that with no output schema the agent gets no sense of what a job record contains or what error surface to expect.

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 both parameters are already documented, and the description's 'optionally with its custom field values' merely restates with_custom_fields. Baseline 3 is appropriate when the schema does the work and the description adds no format or default detail.

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 ('One job by id') plus the optional custom-field expansion, which clearly distinguishes it from bulk listing. It doesn't explicitly name fieldpulse_list_jobs or fieldpulse_get_job's other siblings, but the singular-by-id framing makes the distinction obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent infers it should call this when it already has a job id and needs the record. There is no explicit when/when-not guidance, no mention of the list_jobs alternative, and no note on behavior when the id is unknown.

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 only the raw HTTP path, which is structural rather than behavioral — nothing about error/404 behavior, permissions, or whether the location record includes nested relations.

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 zero filler, and the core operation is front-loaded. Slightly under-specified for its length rather than 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?

For a one-parameter read tool with full schema coverage and read-only annotations, the description is just barely sufficient to invoke correctly. With no output schema, it would benefit from a sentence on what a location record contains, but that omission doesn't block 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 coverage is 100% and the single location_id parameter is fully documented with type and bounds, so the baseline is 3. The description's "by id" restates the schema rather than adding format, sourcing, or lookup-hint value.

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?

"One location by id" states the resource and cardinality precisely, and the REST path disambiguates it as a single-record fetch rather than a search. It doesn't name fieldpulse_list_locations as the alternative, but the singular noun makes the distinction inferable.

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 call this versus fieldpulse_list_locations, no prerequisites, and no mention of what happens when the id is unknown. The agent must infer the routing entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the GET endpoint, which is redundant with the read-only annotation, and says nothing about return behavior, auth, or error cases.

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-loaded, with no unnecessary explanation. The second sentence, “GET /payments/{id},” is somewhat redundant given the annotations and adds little beyond the first sentence.

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 single-resource get tool, the schema and annotations cover the invocation requirements and safety profile. However, with no output schema, the description does not mention what a retrieved payment includes or what the caller should expect back.

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 the single required parameter payment_id is documented in the schema. The description adds only “by id,” so the schema is doing the substantive parameter work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and operation: retrieving one payment by its id. It implies the distinction from the sibling list_payments via “One payment,” but does not explicitly name the alternative.

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 guidance on when to use this tool versus list_payments or other payment-related tools. The “by id” wording hints at the required lookup context, but no alternatives, exclusions, or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description only adds the underlying REST endpoint, which is of marginal value; it says nothing about not-found behavior, permissions, 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 short fragments, front-loaded with the purpose. Nothing is wasted, though the HTTP endpoint line is arguably filler for an agent that cannot call REST directly.

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 lookup with full schema coverage and safety annotations, the description is minimally sufficient. It still leaves gaps around failure modes (invalid or missing id) and whether related sub-resources are included.

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 the single project_id parameter is documented in the schema itself. The description adds no format, source, or validation detail beyond what the schema already provides, 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?

The description states a specific verb and resource ('One project by id') and disambiguates from list_projects by making clear it returns a single record. It stops short of naming the sibling tool explicitly, but the meaning is 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?

There is no guidance on when to use this versus fieldpulse_list_projects, no mention of prerequisites, and no note on what happens when the id is unknown. The agent is left to infer all selection logic 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 safety is covered. The description adds the underlying REST path GET /purchase-orders/{id}, which is mildly useful for tracing behavior, but it says nothing about errors for missing ids or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero waste and the resource identified up front. The API path is arguably filler, but the definition is efficiently sized for a trivial getter.

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 with full annotation coverage and full schema coverage, the essentials are present. However, with no output schema, the description does not hint at what a purchase order object returns, leaving return expectations unset.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With one parameter at 100% schema description coverage, the schema already documents purchase_order_id as a positive FieldPulse purchase order id. The description's "by id" adds nothing beyond that, 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?

"One purchase order by id" states a specific resource and scope, unambiguously distinguishing a single-record fetch from the sibling fieldpulse_list_purchase_orders without naming it. The verb is only implied by the title, but the intent is still clear.

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. The agent must infer that this is the choice when a purchase_order_id is already known and that list_purchase_orders is for searching.

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 and external reach are covered. The description adds only the HTTP endpoint, which is mildly useful context but says nothing about not-found handling, response contents, or whether related resources are expanded. With annotations carrying the main burden, this is adequate but thin.

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 padding, with the core purpose front-loaded before the endpoint detail. Nothing in the text 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?

This is a simple single-parameter read tool with no output schema and full annotation coverage, so the definition is workable as-is. However, with no output schema the description could reasonably say what a vendor record contains or whether the call fails for unknown ids, which it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% – vendor_id is typed as a positive integer with a description ('FieldPulse vendor id.') and a minimum constraint. The description adds nothing beyond the schema (no format hints, no sourcing guidance such as where to get a vendor id), 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?

The description states a specific retrieval operation ('One vendor by id') plus the underlying endpoint GET /vendors/{id}, so an agent immediately knows it fetches a single vendor record by identifier. The singular 'one vendor' implicitly contrasts with the sibling list tool fieldpulse_list_vendors, though it never names it 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: 'by id' signals that this is the tool for fetching a known vendor, as opposed to enumerating vendors. There is no explicit statement of when to prefer this over fieldpulse_list_vendors, nor any prerequisites or error conditions (e.g., what happens with an unknown 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, and the description adds nothing beyond repeating the GET verb. It says nothing about pagination behavior, ordering, or whether the category list is complete or filtered by account scope.

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 terse sentences, front-loaded with the purpose. The endpoint string adds little, but nothing is bloated.

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 zero-required-param list tool with fully documented parameters and safety annotations, this is largely sufficient. The absence of output schema means an agent gets no sense of the returned category shape, 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 page/limit/search are fully documented in the schema, including the next_page handoff hint. The description adds no extra meaning, which lands at 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 asset categories'), which is clearly distinct from the closest sibling fieldpulse_list_assets. However, it does not explicitly contrast itself with that sibling or clarify what an 'asset category' is.

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 the many other list_* tools, no prerequisites, and no mention of alternatives. An agent must infer that categories are a lookup dimension for assets.

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 by structured data. The description adds only the underlying endpoint (GET /assets); it says nothing about default page size, result caps, or what a page of results contains, which would be genuine added context for a list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose, with no redundant restatement of the title. The trailing "GET /assets" is low-value for an agent since the HTTP route is not something it can act on.

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 endpoint with a 75%-documented schema and no output schema, the description covers what the tool does and its main filter axis. Missing details on the return payload (asset shape, next_page pagination behavior) are largely implied by the page/limit schema descriptions, so no critical gap remains.

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 75%, so page, limit and search are already documented; the notable gap is the status enum, which has no schema description. The phrase "by install status" partially compensates by tying status to install state, but it does not explain what each enum value means or how search interacts with status. 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/search customer assets, i.e. equipment) plus the primary filter dimension (install status), which is enough to distinguish it from fieldpulse_get_asset (single-record fetch) and fieldpulse_list_asset_categories. It does not explicitly name any sibling, but the singular/plural and list-vs-get split makes the distinction inferable.

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?

"List or search ... by install status" implies both the browsing and the search use case, so usage is implied rather than stated. There is no explicit guidance on when to prefer this over fieldpulse_get_asset for a known ID, nor any 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint mapping and the set of supported parent record types, but says nothing about ordering, pagination, or what happens with no filters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence plus the endpoint fragment; nothing is padded. Slightly terse for a tool with four parameters, but efficient.

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, yet the description does not indicate the return shape or whether all comments across record types are paginated the same way. For a simple read-only list operation with mostly documented params this is adequate but thin.

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 75% – page, limit and object_id are documented in the schema, along with the pairing constraint between object_id and object_type. The description adds no meaning 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 and resource ('List comments on a record') and enumerates the valid parent record types, plus the underlying endpoint. It is unambiguous and, since no sibling tool deals with comments, no sibling differentiation is required.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus related tools (e.g., listing subtasks or fetching a job), no note that object_id and object_type must be supplied together, and no prerequisites or pagination behavior described. Usage is only inferable from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the shape of returned fields, but says nothing about pagination defaults, total counts, or what happens when search matches nothing.

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 clauses, resource first then endpoint, with zero filler. Slightly telegraphic style but appropriately sized for a simple read tool.

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 usefully names the returned fields (name, address, contact details, settings), which is enough for an agent to decide whether to call it. Only missing piece is any note on paging behavior or whether the search param narrows by name.

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?

All three parameters (page, limit, search) have full schema descriptions, so the schema carries the semantics. The description only hints at plurality via 'profile(s)' and adds no syntax or format detail beyond the schema 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 resource (company profile of this FieldPulse account) and enumerates the fields returned (name, address, contact details, settings), plus the underlying endpoint. It is clearly distinguishable from siblings like list_customers or list_users, though the verb is only implied by the name rather than the description.

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 call this versus alternatives, no prerequisites, and no exclusions. The only usage signal is implicit in the resource name 'company profile' — an agent must infer that this is the account-level record rather than a per-entity list.

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 only the raw endpoint 'GET /contracts' and a parenthetical synonym; it says nothing about pagination, total counts, sorting, or what is returned, which is the actual behavioral gap for a list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two terse sentences, front-loaded with the resource and synonym. The raw endpoint reference is slightly redundant but not harmful; 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 no output schema, the description is the only place to learn what a contract record contains or how results are paged/counted, and it provides none of that. For a simple single-optional-param list call this is minimally viable but leaves the return shape opaque.

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 'limit' parameter is fully documented with range and default. The description adds no parameter meaning beyond the schema, 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?

States a specific verb+resource ('List contracts') and clarifies the domain term by equating contracts with maintenance agreements. The plural 'List' versus the singular sibling fieldpulse_get_contract implicitly signals the distinction, though the description 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?

There is no guidance on when to use this list tool versus fieldpulse_get_contract for a single record, nor any mention of pagination behavior or filtering. The agent must infer the use case 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the HTTP endpoint and does not expand on permissions, response shape, pagination behavior, or other operational context beyond what annotations and schema already provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, front-loaded with the resource scope, and contains no filler. Every sentence contributes directly to identifying the tool.

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 tool with fully documented parameters and annotations covering safety, the description is minimally sufficient. However, it does not help distinguish this listing tool from get_customer_contact or provide usage context, leaving some gaps despite the low overall complexity.

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 three parameters are documented in the schema, including pagination semantics. The description adds no parameter-specific meaning beyond what the schema already provides, making the baseline score 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 identifies the resource clearly as the contacts (people) of one customer and includes the underlying GET endpoint, which implies a list operation. It is distinguishable from get_customer_contact and list_customers by name and resource scope, though it does not explicitly contrast with those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives such as get_customer_contact for a single contact or list_customers for customer records. Usage is only implied by the description and tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description only adds the HTTP verb/endpoint ('GET /customers'), with no note on result size, pagination behavior, or whether an empty search returns everything.

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 fragments, front-loaded with the verb and scope, with no filler. It is arguably terse to the point of omitting useful guidance, 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 a five-parameter read-only list tool with no output schema, the definition covers purpose and searchable fields, and pagination lives in the schema. It still says nothing about default result ordering, how results are returned, or how this relates to the many sibling list_* tools.

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 80%, so the page, limit, search and sort_dir parameters are already documented in structured data. The parenthetical field list adds a hint about what free-text search covers, but it is ambiguous whether 'status' and 'assigned user' are searchable or filterable, and no filter parameters actually exist 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+resource (list or search customers) and enumerates the attributes covered (name, email, phone, address, status, assigned user), plus the underlying endpoint. It is clearly distinguishable from fieldpulse_get_customer, though it never names the 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?

The phrase 'List or search' implies bulk retrieval / querying rather than single-record fetch, which lets an agent infer the split with fieldpulse_get_customer. However, no explicit when-to-use, when-not-to-use, or alternative routing is 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 only the backing endpoint (GET /custom-fields); it does not say whether the listing spans all objects by default, whether pagination must be followed, or what a definition record contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, both front-loaded, with the resource and the optional filter stated immediately. The trailing "GET /custom-fields" is modest technical filler but not harmful.

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-parameter read-only list tool with annotation coverage and an inline-documented pagination scheme in the schema, the description covers what is being returned and the one meaningful filter. No output schema exists, so a brief note on result contents would help, 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?

Schema coverage is 67%: page and limit are documented in the schema, while object_type has only an enum and no description. The description partly compensates by framing object_type as an optional single-object-type filter, but it adds no detail on default behavior when omitted. 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 custom field definitions") plus an optional scope ("for one object type"), which is enough to distinguish it from the many other list_* siblings by resource name alone. It stops short of explicitly contrasting with any alternative, but the resource is 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?

"Optionally for one object type" implies when the filter is relevant, but there is no explicit when-to-use guidance, no stated exclusions, and no mention of when an agent would need custom field definitions at all (e.g. before creating or updating records). Usage is inferable 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint and hints at returned record contents (customer, status, totals, line items), which is modest but real value given there is no output schema; it says nothing about rate limits, default sort order, or total-result behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence plus the endpoint, front-loaded with the verb and resource. Nothing is wasted, though the parenthetical is the least reliable part of 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 five-parameter, zero-required list tool with no output schema, the description should clarify search semantics and result shape. It gestures at returned fields but does not explain how free-text search matches, what the default ordering is, or how results relate to the get_estimate sibling.

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 page, limit, search, sort_by, and sort_dir are all documented in the schema itself, making 3 the baseline. The description adds no parameter-level meaning and its parenthetical field list could mislead an agent into expecting structured filters that do not exist.

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 ('List or search estimates') with the underlying endpoint, which cleanly separates it from the singular fieldpulse_get_estimate sibling. The parenthetical field list (customer, status, totals, line items) is ambiguous about whether those are filters or returned fields, since the schema exposes no such filter parameters.

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?

'List or search' implies bulk retrieval and free-text querying, but the description never states when to use this over fieldpulse_get_estimate or how to combine search with pagination. Usage is left to inference from the verb.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description reinforces this with 'GET /invoices' and hints at searchable invoice data, but it does not add details about auth, rate limits, or response behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence plus the HTTP endpoint. It is front-loaded, waste-free, and easy to scan.

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 tool with full schema descriptions and strong annotations, the description supplies the operation, endpoint, and some field context. It could be more complete by distinguishing this from fieldpulse_get_invoice or clarifying that search is free-text, but it is broadly sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so page, limit, search, sort_by, and sort_dir are already documented in the input schema. The description adds some context about invoice fields that may be searchable, but it does not clarify parameter behavior beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List or search invoices,' and adds the relevant invoice domains in parentheses. It is clear what the tool does, but it does not explicitly distinguish it from the sibling fieldpulse_get_invoice or from other list tools.

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 'List or search invoices,' but the description gives no explicit when-to-use guidance, prerequisites, or alternatives such as fieldpulse_get_invoice. An agent can infer the basic use case but must decide sibling selection on its own.

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 and openness profile is structured data, not description work. The description adds little beyond the raw endpoint (GET /items), and says nothing about whether the catalog is paginated or how large it may be, which matters given openWorldHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence that front-loads the resource and its meaning, with no filler. The trailing endpoint reference is compact and functional.

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 two-param, no-required-argument list tool with full schema coverage and no output schema, the description is nearly sufficient — the agent knows what it returns conceptually (products/services with prices). Only paging expectations for a potentially large catalog are left entirely to the 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% and both parameters (page, limit) are documented in the schema with defaults and ranges, so the description carries no obligation here. It adds no paging guidance of its own, 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 and resource ('List the invoice item catalog') and disambiguates what 'items' means in this domain by glossing it as products and services with prices. This clearly separates it from fieldpulse_get_item, though it doesn't name 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 verb 'List' versus the sibling get_item — an agent can infer this is the browse-all path — but the description never states when to choose it, e.g. to discover item IDs before calling get_item, nor any 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered externally. The description adds little behavioral context beyond the bare 'GET /jobs' endpoint string — it does not discuss pagination behavior, result volume, or how filtering interacts, all of which matter for a 9-parameter listing 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?

A single front-loaded sentence plus a short endpoint tag, with no filler. It is efficient, though the parenthetical facet list is partly wasted because those facets are not exposed as parameters.

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 listing tool with no output schema, the description's claims are accurate and it omits only details already carried by the schema. Nothing critical to correct invocation 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 89%, so the schema already explains page, limit, search, sort, created range, status_ids, and with_custom_fields in detail. The description only echoes the created-at range and status-id filters and says nothing about search, sorting, or with_custom_fields, so it adds marginal value on top of an already well-documented schema (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?

The description states a clear verb and resource ('List or search jobs') and names the facets it covers, which distinguishes it from the singular get_job sibling. However, it lists filters (type, customer, schedule, assignments) that do not obviously map to any schema parameter, so the stated purpose is slightly broader than what the tool actually accepts.

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 'list or search' plus the note that results can be narrowed by created-at range or custom status ids. There is no explicit when-to-use/when-not guidance and no routing to alternatives such as get_job for a single job or list_job_workflow_statuses for discovering status ids; the status_ids schema description, not the tool description, carries that pointer.

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 the safety profile is covered. The description adds the endpoint path and the downstream id-consumption pattern, which is useful. It says nothing about result volume or ordering behavior, though the limit param at least hints at paging.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence plus an endpoint reference; no filler. The cross-reference instruction is front-loaded, though the parenthetical makes the opening slightly less scannable than a plain verb-first statement.

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, single-optional-parameter list tool with no output schema, the description covers what the records are and why an agent would fetch them (id lookup for statuses and custom status setting). Only minor gaps remain, such as whether results are paginated 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% and the single limit parameter is fully documented (range 1-100, default 25) in the schema. The description adds no parameter information and does not mention pagination, 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?

Names the resource (job status workflows) and the underlying endpoint GET /jobs/status-workflows, and implicitly frames it as a listing by referencing ids for downstream use. It is clearly distinguishable from the sibling fieldpulse_list_job_workflow_statuses (workflows vs. statuses within a workflow). It stops short of an explicit verb like 'list all,' relying on the name/title for that.

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 tells the agent what the returned ids are for: passing to fieldpulse_list_job_workflow_statuses and when setting a custom job status. That gives a concrete next-step and sibling routing. No when-not guidance, but for a simple read-only lookup list there is little ambiguity to resolve.

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 structurally. The description adds only that IDs are returned for reuse; it says nothing about pagination behavior despite the limit parameter, or about whether all workflows are always present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence stating the resource and the value of the returned IDs, followed by the raw endpoint. It is compact and wastes little, though the trailing GET path adds marginal value for 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?

For a simple read-only list tool this covers the essentials, but with no output schema the description should say more about the return shape beyond 'ids' — e.g. status names, workflow grouping, or pagination cues — to fully prepare an agent for the response.

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 the single limit parameter is fully documented in the schema (1-100, default 25). The description adds no additional meaning about paging or result-size tradeoffs, 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?

The description names a specific resource — the custom job statuses of all workflows — and clarifies that IDs are included for use in job filtering or status setting. It is clearly distinct from the sibling fieldpulse_list_job_status_workflows (which returns the workflows themselves), though it does not explicitly say so.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical '(for filtering jobs or setting a status)' implies a downstream use case, so an agent can infer when to reach for this tool. However, there is no explicit when-to-use/when-not guidance and no sibling alternative named for related lookups.

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 fully covered structurally. The description adds only the raw endpoint path 'GET /lead-source', which gives no additional behavioral context such as result shape, ordering, or whether the list is tenant-scoped.

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 purpose, with no filler. The endpoint path is of marginal value but is brief enough not to be waste.

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, annotation-covered read tool with only two optional paging params, so the bar is low. Still, with no output schema the description could have said what a lead-source record looks like or whether results are paginated, which would make it self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: page and limit are both documented in the schema, including the 'pass the previous reply's next_page' chaining hint. The description adds nothing about parameters, 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 customer lead sources') so an agent knows exactly what comes back. It is distinguishable from write siblings like fieldpulse_create_customer, but it doesn't distinguish itself from the many other list_* enumeration tools in the namespace.

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 mention of prerequisites such as needing a customer context or that this is a reference-data lookup rather than a customer-scoped query. The agent must infer applicability entirely from the name.

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

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

Annotations already declare readOnlyHint, destructiveHint:false and openWorldHint, so safety is covered. The description adds only a REST path ('GET /locations') and nothing about result volume, pagination behavior, or whether unfiltered listing is allowed — little beyond structured data.

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 verb and resource; no filler. The brevity is efficient but stops just short of the point where extra detail would be useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should say what a returned location record contains and how paging is surfaced (the schema hints at next_page but the description does not). For a simple read-only list tool this is adequate but leaves real 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 coverage is 75%, with the object_type enum carrying no per-value description. The description indirectly documents the enum's meaning ('of a customer or a job') and reinforces that object_id is a customer or job id, but adds no format, defaulting, or interaction rules 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 and resource ('List locations') and clarifies what a location is ('service addresses'), plus the domain scope (of a customer or a job). It does not explicitly distinguish itself from the sibling fieldpulse_get_location or from other list_* tools, so it falls 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?

No guidance on when to use this versus fieldpulse_get_location for a single record, or versus listing customers/jobs. All four parameters are optional, yet the description never says what happens when object_id/object_type are omitted (all locations vs. error), which is exactly the decision an agent needs to make.

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, destructiveHint=false, so safety is covered. The description only adds the underlying endpoint (GET /payments) and nothing about pagination behavior, whether search and sort combine, or rate limits — useful context but thin against an already-annotated read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler and the endpoint tucked at the end. It is efficiently sized, though the parenthetical is slightly ambiguous about whether those are search targets or sortable columns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter, zero-required read tool with no output schema and full annotation coverage, the description is minimally adequate. It omits the shape of returned records and the interaction between paging, search, and sorting, which an agent would need to call it well.

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 80%, so the schema already documents page, limit, search, and sort_dir; only sort_by lacks a description. The parenthetical hints at sortable/filterable attributes but does not explain how the free-text `search` relates to those fields or which fields it scans, so it adds little beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"List or search payments" gives a specific verb pair plus the resource, and the parenthetical enumerates the payment attributes in play (amount, method, date, invoice). This clearly separates it from fieldpulse_get_payment, but it never explicitly says it returns a collection while get_payment returns one record.

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?

"List or search" implies two usage modes and the plural resource implies bulk retrieval, so an agent can infer the list-vs-fetch distinction. However, no alternative is named (fieldpulse_get_payment, fieldpulse_list_invoices) and there are no conditions or exclusions stated for choosing search over paging.

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 only the underlying endpoint (GET /pipeline-status), with no mention of pagination behavior or result ordering, so it contributes little beyond structured data.

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 the resource named first, which is front-loaded and efficient. It is close to minimal, though the endpoint mention is arguably redundant with the structured metadata.

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 paginated list tool with full schema coverage and annotations, the description covers the core purpose but omits any hint of return shape or ordering. With no output schema present, the description could reasonably say more about what a pipeline status record looks like.

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 the page/limit semantics including defaults and the next_page handoff are fully documented in the schema. The description adds nothing about parameters, which is acceptable at full coverage but provides no extra value.

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+resource ("List customer pipeline statuses"), which is clearer than the title alone. However, it does not distinguish itself from nearby siblings like fieldpulse_list_job_status_workflows, fieldpulse_list_job_workflow_statuses, or fieldpulse_list_lead_sources, leaving the agent to infer the difference.

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 tool versus alternatives, and no exclusions or prerequisites are given. The agent must infer usage purely from the tool name and the ambiguous phrase "pipeline statuses."

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 fully covered. The description adds only the raw endpoint path and restates the search capability that is already visible as a schema parameter; it says nothing about pagination behavior, result ordering defaults, or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short fragments, front-loaded with the verb and resource, with zero padding. The trailing 'GET /projects' is mild filler that a model cannot act on but costs little.

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 five parameters, the description should at least indicate what a project record contains or how pagination/sorting resolve. It leaves the return shape entirely unspecified and gives no hint about default ordering or the meaning of sorting by 'cuid'.

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 80% with page/limit/search/sort_dir already documented inline, so the baseline is 3. The description adds no parameter meaning and the '(status, completion)' parenthetical arguably introduces confusion, since 'status' is not a filter or sort option here (only status_id in sort_by) and completion is only a sort key.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List or search projects') and adds the underlying endpoint. It does not distinguish this from the sibling fieldpulse_get_project (single-project fetch), and the parenthetical '(status, completion)' is ambiguous about whether those are filters, returned fields, or sort options.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no exclusion, and no pointer to fieldpulse_get_project for a single record. The agent must infer from the name alone that this is the collection endpoint rather than the detail endpoint.

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 fully covered elsewhere. The description adds only a REST endpoint string ("GET /purchase-orders"), contributing no behavioral context such as whether results are unpaginated by default, what ordering is returned, or what happens when page exceeds the result set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short and front-loaded, but the second sentence ("GET /purchase-orders") is redundant REST trivia that does not help an agent decide or invoke correctly — the space could have carried usage guidance instead.

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 two-parameter read-only list tool with an exhaustive schema and rich annotations, the minimal description is roughly adequate. However, with no output schema, the agent gets no indication of what a purchase order record contains or how pagination termination is signaled, leaving a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (page, limit) have well-written inline descriptions including defaults and the "pass the previous reply's next_page" hint. The description adds nothing 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?

The description names a specific verb and resource ("List purchase orders"), which is enough for an agent to distinguish it from fieldpulse_get_purchase_order (singular fetch) and from the many unrelated list_* siblings. It stops short of any explicit sibling differentiation in prose, relying on the tool name to do that work.

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 list endpoint versus fieldpulse_get_purchase_order, nor any note about prerequisites, pagination strategy, or expected volume. The agent must infer the paginated-collection use case entirely from the name and schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint and resource clarification, but does not mention pagination behavior, return shape, 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?

Two short sentences with the core resource and filtering dimensions front-loaded; 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?

This is a moderate six-parameter list tool with no output schema, and annotations cover the read-only safety profile. The description identifies the resource and main filters but leaves sorting, pagination behavior, and return shape largely to the schema or inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema description coverage, the schema already documents page, limit, assigned_user_id, and sort_dir. The description only names status and assigned_user_id as filters and adds little explanation for sort_by, sort_dir, or pagination beyond what the schema 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?

The description states a specific verb and resource ('List subtasks') and clarifies that subtasks are job checklist items, which helps distinguish the resource. It does not differentiate this list endpoint from sibling list/get tools such as fieldpulse_list_jobs or fieldpulse_get_job.

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 'by status or assigned user' implies that this tool is used for filtered subtask retrieval, but there is no explicit guidance on when to use it versus sibling tools, nor any when-not-to-use conditions 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, openWorldHint=true and destructiveHint=false, so safety is fully covered structurally. The description only adds the endpoint ('GET /tags') and that tags are scoped by customer or job — no pagination behavior, no rate/limit context, no indication of what a tag record contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler and the purpose front-loaded. It is efficient, though the terseness borders on under-specification rather than deliberate brevity.

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 tool with zero required parameters and no output schema, the description is adequate but thin. It never explains what a returned tag looks like or how pagination termination works, which an agent needs for multi-page retrieval.

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 67%: page and limit are well documented in the schema, while object_type has an enum but no description there. The phrase 'for customers or jobs' loosely maps to the object_type enum values, but adds no detail on default behavior when omitted. 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 (tags) plus the scope ('for customers or jobs'), which is enough to distinguish it from the many other list_* siblings since no other tag tool exists. It stops short of naming a specific alternative, but the purpose is 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?

There is no guidance on when to call this versus other tools, whether object_type is required to get useful results, or how to page through results. The agent must infer usage entirely from the schema.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is carried by structured data. The description adds only the raw endpoint path "GET /teams", which is essentially redundant with the name and adds no rate-limit, pagination, or ordering context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no filler; the purpose is stated before the endpoint reference. Nothing an agent must read through before acting.

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 two-parameter read-only list tool with no output schema, the safety hints and full schema coverage leave few gaps. What is missing is only what a team record contains and whether results are ordered, which 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%; both page and limit are documented in the schema, including the useful "Pass the previous reply's next_page" chaining hint. The description adds nothing on top, 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 the account's teams") and scopes it to the account, which is enough to separate it from sibling list tools like fieldpulse_list_users or fieldpulse_list_locations. It stops short of explicitly naming an alternative, so it lands just under 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?

There is no statement of when to use this tool, when not to, or which sibling it replaces for related data. An agent must infer from the name alone that this is the unfiltered enumeration of teams.

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, covering the safety profile. The description adds the endpoint (GET /timesheets), confirming a simple read, but says nothing about pagination behavior, result volume, or default page size beyond the limit param.

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, front-loaded sentences with the resource scope stated first and the endpoint appended. Little waste; the trailing 'GET /timesheets' is marginally redundant but 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 simple parameterless-required list tool with a fully documented schema and annotations covering its behavior, the description is largely sufficient. The only gap is pagination/return-shape context, but with no output schema and a clear limit param this 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 all five parameters are documented in the schema itself. The description alludes to user and time-window filtering, mapping to user_id/in_time/out_time, but adds no format or interaction detail beyond what the schema provides. 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 clear verb (List) and a specific resource (timesheet entries, clarified as clock in/out), which an agent can understand without opening the schema. There is no competing timesheet sibling, so explicit differentiation isn't required, but the description also doesn't contrast scope with other list tools.

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 'optionally for one user or a time window' implies the filtering conditions the tool supports, giving some usage context. However, it never states when to call this versus alternatives or notes that all filters are optional (returning everything).

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 underlying endpoint GET /users and the purpose of the returned ids, but does not disclose pagination behavior or what constitutes a 'user' record.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is two short clauses with the resource and purpose front-loaded, followed by the endpoint. There is no redundant or 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 simple read-only list tool with one fully documented parameter and annotations covering safety, the description is minimally adequate. However, with no output schema, it does not indicate what a returned user record contains or whether inactive users are included.

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 the single limit parameter (1-100, default 25) is fully documented in the schema. The description adds no parameter-specific meaning, which is acceptable given the schema already does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: listing the account's users, clarified as team members, with ids intended for assignments. This clearly distinguishes it from get_* tools, though it does not explicitly contrast with other list_* tools.

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 'with ids for assignments' implies a usage context — retrieving user IDs to reference elsewhere — but there is no explicit when-to-use guidance, prerequisites, or named alternative tool. Usage is inferable 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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds nothing behavioral beyond that — no note on pagination defaults, result ordering, or search behavior — it only restates the HTTP endpoint, which is not useful to an agent.

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 terse fragments, front-loaded with the resource name; nothing is padded. The GET /vendors line is arguably wasted text since no other vendor endpoint is exposed via HTTP path here.

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 two-optional-parameter read tool with full annotation coverage, the description is minimally adequate. It omits any hint about the shape or size of the returned vendor list (no output schema exists), leaving the agent to discover that at call time.

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 limit and search semantics (range 1-100, default 25, free-text) are fully documented in the schema. The description contributes no additional meaning, which is acceptable given the schema baseline of 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 vendors") and adds the synonym "suppliers" to broaden recognition. It is distinguishable from the singular fieldpulse_get_vendor by the list verb, though it does not name 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?

No guidance on when to use this versus fieldpulse_get_vendor or other list endpoints, and no prerequisites or exclusions. The agent must infer usage purely from the verb.

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 write/destructive/idempotent, so the bar is lower, and the description still adds non-obvious context: the operation is a partial field-level change and is backed by PUT /customers/{customerId}. It does not disclose what happens to omitted fields explicitly or how uniqueness errors on display_name surface, but the partial-update semantics are real 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?

Two tight sentences plus an endpoint, with the WRITE marker and the partial-update caveat front-loaded. Nothing is wasted and the most decision-relevant fact 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?

For a 29-parameter mutation with no output schema, the description covers the write action and naming rule but omits mutation mechanics an agent would want (omitted-field behavior, permission/auth expectations, failure modes such as duplicate display_name). Adequate but thin for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 29 parameters and only 28% schema description coverage, the description should carry far more weight than it does; it only clarifies the first_name/last_name/display_name trio and says nothing about tags, assigned_to, lead_source_id, pipeline_status_id, or the address fields. Most parameters are left for the schema to imply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (change) and resource (one customer), and the parenthetical "only the fields you pass" pins down that this is a partial update rather than a replacement, which separates it cleanly from fieldpulse_create_customer and fieldpulse_get_customer. An agent knows exactly what operation it is choosing.

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 one conditional rule ("If FieldPulse asks for a name, include first_name/last_name or display_name"), which is genuinely useful for satisfying the API, but never says when to prefer this over create_customer or how to obtain a customer_id first. Usage 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?

Beyond the annotations, it discloses a non-obvious platform constraint (customer_id, job_type and billing are mandatory on every update), explains the compensating read-then-write behavior, warns that this is two requests, and flags the absence of a version check — i.e., last-write-wins concurrency risk. This is exactly the operational context 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?

Four short sentences, mutation intent and the endpoint front-loaded, then the required-field quirk, then the atomicity caveat. No filler and 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 an 18-param mutation tool with no output schema, the description covers the essential gotchas an agent needs to call it correctly. It is thin only on error behavior (e.g., invalid job_id, what a failed read-modify-write leaves behind), which is a minor residual 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?

With 18 parameters and only 56% schema description coverage, the description usefully explains that customer_id/job_type/billing/current status are auto-preserved unless overridden, which the schema alone does not state. It does not add meaning for several bare parameters (notes, field_notes, subtitle, tags), leaving part of the coverage gap unaddressed.

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?

Opens with a specific verb and resource ("WRITE: change a job") and enumerates the mutable facets — status, schedule, notes, assignments, location — plus the concrete endpoint PUT /jobs/{jobId}. It is clearly distinguishable from fieldpulse_create_job and fieldpulse_get_job 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 "WRITE:" prefix and "change a job" make it evident this targets an existing job rather than creation, and it describes partial-update semantics ("keeps those ... unless you pass new values"). However, it never explicitly contrasts with siblings like fieldpulse_create_job or states when not to use it.

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