JobNimbus MCP by usefulapi

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

Adds behavioral context beyond the annotations by warning 'Workflow automations may fire', which is a genuine side effect an agent should know before writing. The destructiveHint=true annotation is not contradicted, though the description doesn't discuss idempotency or duplicate handling.

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

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

Four short, front-loaded sentences: purpose, field constraint, required workflow/status plus prerequisite, then side effect and endpoint. Slightly redundant first sentence repeats the title, but there is little 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?

For a 23-parameter mutation with a nested custom_fields object and no output schema, it covers the essentials: required fields, the cross-field rule, the settings prerequisite, and side effects. It could note identifier return behavior, but with no output schema that is not required.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a cross-field constraint absent from the schema: at least one of first_name, last_name, display_name or company. The workflow/status matching rule also adds semantics the minLength-only schema fields don't convey.

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

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

States a specific verb+resource ('Create a contact') and immediately names the domain-specific fields it operates on, cleanly distinguishing it from siblings like jobnimbus_create_job, _create_note and _create_task.

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

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

Gives a real prerequisite: record_type_name and status_name 'must match the account settings (jobnimbus_get_account_settings)', routing the agent to the lookup tool first. It does not, however, say when to use this versus jobnimbus_update_contact for an existing contact.

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 only declare destructiveHint=true, so the description earns credit for disclosing the real side effect that "Workflow automations may fire" and that identity fields are validated against account configuration (a common failure mode). It still doesn't say what happens on validation failure or what the created record 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?

Dense and front-loaded: required fields first, then linking, then side effects, then endpoint. Every sentence carries information, though the parenthetical examples make a few clauses run long.

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 create tool with a nested custom_fields object and no output schema, the description covers the required-field contract, contact linking, and the automation side effect adequately. The absence of return-value explanation is acceptable given no output schema exists.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: record_type_name is clarified as a job workflow (e.g. Residential) and status_name as a status within it (e.g. Lead), and primary_contact_id is explained as the homeowner link. That resolves the ambiguity in the terse schema strings.

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 ("Create a job (project)") and names the concrete identity fields that define the object, which cleanly separates it from jobnimbus_create_contact, create_task, and create_note. The trailing endpoint note (POST /jobs) confirms the resource unambiguously.

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?

States the three required fields and the constraint that they must match account settings, plus how to link the homeowner via primary_contact_id — enough context to attempt a correct call. It does not explicitly contrast with jobnimbus_update_job or note that jobnimbus_get_account_settings should be consulted first to discover valid workflow/status names.

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 supply only destructiveHint=true and a title, so the description carries most of the behavioral burden. It states the write and the underlying endpoint (POST /activities) but says nothing about side effects on the activity feed, notification behavior, or reversibility - notable gaps for a mutating tool whose destructiveHint is the only annotation.

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

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

Three short sentences with the purpose front-loaded and no filler. The trailing endpoint reference is compact, though partly internal implementation detail rather than agent-facing guidance.

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 create tool with full schema coverage and no output schema, the description covers purpose and the record_type_name default but omits any guidance on required-field effects, feed visibility, or the actor permission nuance that the schema does handle. Adequate but with clear gaps for a mutation.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the record_type_name default. The description adds only a marginal pointer that alternate activity types come from account settings; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource - adds a note/activity entry to a contact or job's activity feed - and specifies the target entity, which cleanly separates it from jobnimbus_create_contact, jobnimbus_create_job, and jobnimbus_create_task. An agent can identify the operation 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?

It explains that record_type_name defaults to Note and that alternative activity types come from account settings, which is useful in-tool guidance. However, it offers no when-to-use versus alternatives context (e.g., versus create_task or list_activities) and no prerequisites for the mutation, so guidance 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 only declare destructiveHint=true, which the description is consistent with via 'Create' (POST /tasks), so there is no contradiction. The description adds the endpoint and required-field constraints, but says nothing about permission requirements for acting on another record, side effects, or whether the created task can be undone — meaningful gaps for a write tool whose annotation burden is only partially covered.

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 with the required-field contract and the linking rule front-loaded, no filler, and the endpoint tacked on last. 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 10-parameter mutation tool with no output schema, the description covers the required contract and one key parameter's source, but leaves the return value (e.g. the new task's jnid) and error/permission behavior unexplained. Adequate to invoke, not complete enough for an agent to handle the result confidently.

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

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

Schema coverage is 100%, so the baseline is 3, yet the description adds genuine meaning: it names the three required fields plus related_id, clarifies date_start is unix seconds and doubles as due time, and explains record_type_name comes from account settings (e.g. Task or Appointment), nudging the agent toward get_account_settings. It does not cover the other optional params, so it stops short of a 5.

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

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

The description opens with a specific verb and resource ('Create a task or appointment') and adds scope ('on a contact or job'), so the agent knows exactly what record is produced and what it attaches to. It is trivially distinguishable from sibling creators like create_contact or create_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?

It states the operation and its required inputs, which implicitly tells the agent this is the tool for creating new tasks, but it never states when NOT to use it or points to alternatives such as update_task for modifying existing tasks or list_tasks for retrieval. Usage context is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuine value by enumerating what the response contains (settings categories) and naming the underlying endpoint (GET /account/settings). It does not discuss auth, rate limits, or caching, but for a simple read it discloses the important behavioral 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?

Three tight sentences: what it returns, why to call it, and how to narrow the result, with the cross-reference to create/update tools front-loaded in the middle. No redundant or filler content.

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

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

With no output schema, the description compensates by enumerating the returned setting categories, and with 1 fully-documented parameter and readOnly annotation nothing operational is missing. An agent has everything needed to call this correctly and interpret the result.

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 `field` parameter is already documented with an example in the schema. The description restates the same idea ('Pass field (e.g. groups) to get just one setting') without adding new semantics such as valid field values or default behavior, so it meets the baseline for high coverage.

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

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

States a specific verb (Fetch) and resource (account's configuration) and enumerates the concrete contents: contact/job workflows with statuses, task types, activity types, file types, lead sources. This clearly separates it from the sibling CRUD tools, which operate on individual entities rather than account-wide reference data.

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 explicit usage context: 'Use it to find the exact record_type_name / status_name / source_name values the create and update tools need,' which ties it as a prerequisite to specific siblings. It also explains the `field` filter. It stops short of an explicit when-not (e.g. don't call repeatedly for per-record data), so it is clear but not exhaustive.

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, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned field groups (name, company, phones, email, address, workflow status, lead source, sales rep, custom fields), which matters because there is no output schema. It does not mention auth scope, rate limits, or missing-record 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?

Front-loaded with the action and the returned payload in a single tight sentence; the trailing 'JobNimbus: GET /contacts/{jnid}' is a minor redundancy that adds little for an agent already holding the tool, but costs nothing materially.

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 no output schema, the description compensates well by naming the returned fields and confirming read-only semantics via annotations. Nothing an agent needs to invoke it correctly is missing, though error/empty-result behavior is unstated.

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

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

There is a single parameter with 100% schema coverage, and the schema already defines jnid as the JobNimbus record id. The description only restates 'by jnid' with no added format or lookup guidance, 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 ('Fetch a single contact by jnid') and enumerates the fields returned, which clearly separates it from the list_contacts sibling by operating on one record. It stops short of naming the alternative explicitly, but the 'single' scope makes the intent 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?

Usage is implied by the required jnid and the singular scope: you call this when you already have a contact id and need the full record. No when-not condition or direct routing to jobnimbus_list_contacts / jobnimbus_update_contact 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, so the safety profile is covered. The description goes further by disclosing the shape of the response (line items, payments applied, total, total_paid, due), which is genuinely useful given there is no output schema. It does not mention auth needs, rate limits, or error 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?

Two short sentences, front-loaded with the action and scope, followed by the returned fields and the underlying endpoint. Every clause carries information; nothing is redundant.

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

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

For a single-record read tool with one fully documented parameter and readOnly annotations, the description is nearly complete, and listing the returned fields compensates for the absent output schema. Only the lack of guidance on failure/not-found behavior keeps it from a 5.

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

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

Schema description coverage is 100% and there is only one parameter, whose meaning ('The invoice's jnid') is fully documented in the schema. The description repeats the jnid lookup concept without adding syntax, format, or validation detail beyond it, 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?

The description states a specific verb and resource ('Fetch a single invoice by jnid') and scopes it to one record, which implicitly separates it from the sibling jobnimbus_list_invoices. It never names the sibling explicitly, so differentiation relies on the word 'single'.

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

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

Usage is only implied: the agent must have a jnid in hand, which is evident from the required parameter. There is no statement of when to prefer this over jobnimbus_list_invoices or jobnimbus_get_job, and no exclusions or prerequisites are given.

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

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

readOnlyHint=true already declares the safe-read profile, and the description adds real value beyond that: it enumerates the returned shape (name, number, workflow/status, address, sales rep, owners, contacts, custom fields) and cites the underlying endpoint. It does not mention not-found/error behavior, which keeps it short of a 5.

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, front-loaded with what is fetched; the trailing endpoint citation is mildly redundant but cheap and useful for debugging. No filler.

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

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

With no output schema and only one parameter, the description compensates by listing the returned fields, which is exactly what an agent needs to plan the call. Error/empty-result handling is the only notable omission.

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 jnid parameter is fully documented in the schema, so the baseline is 3. The description reinforces that jnid is the job's identifier used for the lookup but adds no format or sourcing detail 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 (fetch) and resource (a single job) with the lookup key (jnid), and the field list makes the scope concrete. This clearly distinguishes it from sibling list tools such as jobnimbus_list_jobs and mutate tools like jobnimbus_update_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?

Usage is implied by 'by jnid' — the agent infers it needs a known record id — but the description never says when to prefer this over jobnimbus_list_jobs or how to obtain a jnid. No 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, so safety is covered; the description adds real behavioral value by enumerating the returned fields (title, type, start/end, priority, completion, owners, related records) in the absence of an output schema. It stops short of noting not-found/error 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 front-loaded sentence that pairs the operation with the lookup key, then appends the return payload and endpoint with zero 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 single-record read with readOnlyHint covering safety, the description's field enumeration compensates for the missing output schema. Only error/not-found behavior is left unstated.

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

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

Schema coverage is 100% and the single jnid parameter is fully documented there as the JobNimbus record id. The description's 'by jnid' merely restates 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 (fetch) and resource (a single task or appointment) keyed by jnid, which implicitly separates it from the list_tasks sibling. It does not explicitly name an alternative tool, so it stops short of the top score.

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: 'single ... by jnid' signals this is the direct-lookup path versus listing. There is no explicit when-to-use/when-not guidance or named alternative, leaving the agent to infer the routing.

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

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

The readOnlyHint annotation already covers the safety profile, so the bar is lower. The description adds value beyond structured fields by disclosing the return shape {count, activity}, which matters because there is no output schema, and by clarifying that results include both user notes and system-generated events.

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

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

Two compact sentences: the first front-loads what is listed and the scoping option, the second gives the return shape and endpoint. No filler and nothing buried.

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

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

With six optional params, a nested ElasticSearch filter object, and no output schema, the description does the essential work of naming the return keys and the endpoint. It does not describe the shape of an individual activity object or the filter's relation to the other params, but 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 description coverage is 100%, with pagination, filter syntax, sorting, and related_id all fully documented in the schema. The description only restates related_id and adds no format, default, or interaction detail beyond it, so the 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 (List) and resource (activity entries), and preempts the ambiguity of 'activity' by defining it as notes plus system events like status changes and record creation. It also names the underlying endpoint (GET /activities), letting an agent distinguish it from the create_note and list_* siblings.

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

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

It indicates the optional scoping case — one contact or job via related_id — but gives no explicit when-to-use versus alternatives (e.g., use jobnimbus_list_tasks for tasks, create_note for writing). Usage is implied by the resource scope 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?

readOnlyHint=true already covers the safety profile, but the description adds real behavioral context beyond annotations: default ordering (newest first), the return envelope {count, results}, and the ElasticSearch-style filter mechanism. It does not mention pagination limits or rate limiting, but pagination is covered in the schema.

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

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

Three tight clauses: what it lists, default ordering plus optional filter, and the return shape. The scoping and filter information is front-loaded 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?

With no output schema, the description takes on the burden of return-value disclosure and does provide {count, results}. For a read-only list tool with fully documented parameters, that is nearly sufficient; only the meaning of 'count' (total matches vs. page size) is left ambiguous.

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

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

Schema description coverage is 100%, so the schema already documents from/size semantics, filter syntax with examples, sort_field and sort_direction defaults. The description adds only a generic reference to ElasticSearch-style querying, which the schema demonstrates more concretely. 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 (list/search) and resource (contacts), then enumerates the record subtypes it covers (customers, leads, adjusters, subcontractors), which distinguishes it from the sibling list_jobs/list_tasks/list_invoices. It even names the underlying endpoint, so the agent knows exactly which collection is being read.

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

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

The description conveys that filtering is optional and that results come newest-first by default, which implies 'use this for browsing/querying contacts.' However, it never states when to prefer this over jobnimbus_get_contact for a single lookup, nor any conditions under which filtering is required or unsupported.

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, so safety is covered. The description adds real behavioral context beyond that: the return shape {count, results} and the key semantic that 'count is the account total' rather than the page size, plus the underlying endpoint (GET /v2/estimates).

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 with zero filler: the resource and returned fields come first, then the response envelope and endpoint. Every clause carries information.

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

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

With no output schema, the description correctly takes on the return-shape burden, naming the envelope and clarifying that count is the account-wide total (important for pagination reasoning). Pagination mechanics live in the schema, so nothing critical is missing, though a note on default page size or ordering would round it out.

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 both parameters (from, size) are thoroughly documented in the schema, including offset math and the 25-vs-1000 default discrepancy, so the description need not compensate. The description adds no parameter detail at all, making the baseline 3 correct.

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

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

Specific verb ('List') plus resource ('estimates'), with an enumeration of the returned fields and the response envelope. The resource name alone cleanly separates it from siblings like jobnimbus_list_invoices and jobnimbus_list_jobs.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g., get-invoice-style retrieval or filtered search), and no stated prerequisites. The agent can infer it lists estimates, but nothing tells it when this is the right choice over another list/get 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?

readOnlyHint=true already establishes the safe-read profile, so the description's added value is the explicit 'Metadata only; file bytes are not downloaded' constraint and the 'Returns {count, files}' shape. That is meaningful context beyond the annotation, though permissions or rate-limit behavior are not mentioned.

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 with zero filler: contents first, then the scoping option, then the metadata caveat and return shape. Everything is front-loaded and 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?

With no output schema, the description correctly supplies the return envelope ({count, files}) and the metadata-only caveat, and the rich schema covers pagination and filtering. Minor gaps remain around sorting defaults interplay and permissions, but the essentials an agent needs are present.

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

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

Schema description coverage is 100%, so all six parameters (from, size, filter, related_id, sort_field, sort_direction) are already documented in the schema, including the pagination formula and the filter examples. The description restates related_id's purpose but adds no syntax or format detail beyond the schema; 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 file attachments') and enumerates the returned fields (filename, content type, size, file type, owning contact/job), which cleanly separates it from the sibling list_contacts/list_jobs/list_tasks tools. It also surfaces the underlying endpoint (GET /files).

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 hints at the scoping use case via 'optionally for one record (related_id)', but never states when to reach for this tool versus other list tools or when not to. Usage is implied rather than spelled out.

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

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

With readOnlyHint=true already declaring the safe-read profile, the description still adds real value: it discloses the return shape '{count, results}' and clarifies that count is the *account* total rather than the page count, which is essential for pagination reasoning. It stops short of 5 only because it omits ordering and page-boundary 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?

Three tight sentences, front-loaded with purpose, then returned fields, then return shape and the underlying API path. Every sentence carries information; only the raw endpoint citation is arguably 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?

No output schema exists, so the description compensates by enumerating returned fields and describing the {count, results} envelope. Combined with fully documented params and a readOnly annotation, an agent has enough to call this correctly, though pagination edge cases remain implicit.

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 'from' and 'size' are thoroughly documented in the schema (defaults, ranges, next-page formula). The description adds nothing about parameters, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('List invoices') and enumerates the fields returned, so an agent knows exactly what this produces. It does not explicitly differentiate itself from the sibling jobnimbus_get_invoice (singular) or jobnimbus_list_estimates, so it stops short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance. The description never tells the agent when to prefer this over jobnimbus_get_invoice for a single record, nor does it mention any filter or scoping options (it returns account-wide results). Usage must be inferred 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 only supply readOnlyHint=true, so the description carries the rest and does add value: default sort order, the response envelope {count, results}, and the underlying endpoint (GET /jobs). It stops short of explaining pagination behavior or filter-application costs, which the schema covers only for from/size.

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

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

Front-loaded with purpose and default behavior in one dense sentence, followed by the return shape and endpoint. Every clause carries information, though the trailing 'JobNimbus: GET /jobs' is marginal for an agent that already has the schema.

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

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

With no output schema, disclosing {count, results} is genuinely necessary and done. For a six-parameter tool with a nested filter object, the description is adequate given the schema's 100% coverage, though it says nothing about total-count/pagination semantics beyond what `from`/`size` document.

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%, including a rich example set for the `filter` object, so the baseline is 3. The description's single filter example (status_name term) and the related_id mention largely restate what the schema already documents.

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

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

States a specific verb and resource ('List jobs (projects)') plus the default ordering ('newest first') and the optional filtering behavior. This is unambiguous against siblings like jobnimbus_get_job (single record) and jobnimbus_create_job (write).

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 conveys that filtering is optional and illustrates the filter shapes, but never states when to choose this over jobnimbus_list_contacts or other list_* siblings, nor any exclusions or prerequisites. Usage is implied rather than guided.

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

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

With readOnlyHint=true already covering the safety profile, the description still adds value by disclosing the return envelope ({count, results}) and the underlying endpoint (GET /tasks). It stops short of describing pagination or ordering behavior, though those are documented in the schema.

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

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

Three short, front-loaded sentences with zero padding: purpose, filtering options, then return shape and endpoint. The inline JSON example is compact and earns its place, though the sentence is somewhat dense.

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 six-parameter, no-required-argument list tool with no output schema, the description covers purpose, filtering, and return shape adequately. Remaining details such as sort defaults and page semantics are fully carried by the schema, so 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 description coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description's filter example (is_completed:false) is a marginal addition over the schema's own examples, but it largely restates what the structured field already explains.

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 tasks and appointments") and clarifies the scope of what can be listed. It doesn't distinguish itself from the nearest sibling concerns, such as jobnimbus_get_task for a single task or jobnimbus_list_activities, which could plausibly overlap with "appointments."

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 concrete usage context by naming the two filtering paths (related_id for a contact/job, or an ElasticSearch-style filter) and even shows a worked example for open tasks. However, it never says when to prefer this tool over jobnimbus_get_task or jobnimbus_list_activities, so the guidance is implied rather than explicit.

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

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

The readOnlyHint annotation already establishes this is a safe read, but the description adds useful behavioral context: the endpoint is GET /account/users, and the response includes name, email, id, and active status. It does not cover pagination or rate limits, but it goes beyond the structured fields.

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

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

Two sentences plus a compact endpoint reference. The key output information is front-loaded, and every sentence adds value without repetition.

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 usefully names the fields returned and clarifies what the id is for. For a zero-parameter read tool, this is complete enough for correct selection and 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?

This tool has zero input parameters, so there are no parameter semantics to document. The baseline score of 4 applies; the description appropriately avoids discussing parameters it does not have.

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 JobNimbus users (team members). It also names the returned fields, distinguishing it from sibling list tools for contacts, jobs, tasks, and invoices.

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

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

The description explains that the returned id is what owners, sales_rep, and owner_ids take, which clearly signals when an agent needs this tool. It does not name an explicit alternative or exclusion, but the usage context is strong.

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 only supply destructiveHint=true, so the description does real work: it discloses merge-not-replace semantics, that status_name changes can trigger automations, and that delete/archive are unavailable. It does not cover auth requirements or error behavior, and the 'PUT' endpoint note sits slightly oddly against the stated partial-update 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?

Four tight sentences with the partial-update rule front-loaded, followed by the side-effect warning, the exclusion, and the raw endpoint. No filler.

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

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

For a 24-parameter mutation tool with no output schema, it covers the essentials an agent needs: which fields change, what side effects follow, and what is impossible. Auth/permission detail and error/validation behavior are absent, but the schema's actor description partially compensates.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: that all non-required fields are optional and merged, and that status_name has workflow side effects. It still says nothing parameter-specific about the other 22 fields, including custom_fields behavior.

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 (Edit) and resource (existing contact), and immediately scopes it to partial updates: 'only the fields you pass change.' This cleanly separates it from jobnimbus_create_contact and jobnimbus_get_contact, and adds an exclusion ('Cannot delete or archive').

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

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

Gives clear operating context: partial-update semantics, the workflow/automation consequence of changing status_name, and the explicit limitation that deletion and archiving are not supported. It does not name an alternative tool by name, so it falls short of a 5.

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

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

destructiveHint=true is already supplied by annotations, and the description adds real behavioral context on top: PATCH-like semantics ('Only the fields you pass change'), the side effect that 'Automations may fire', and the record_type_name workaround for rejected status changes. It does not describe the response or error surface, but for a mutation tool this is above the annotation baseline.

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

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

Three compact sentences, front-loaded with the core action, followed by the partial-update semantics, the exception, and the side effect. No filler; every clause carries information.

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

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

With 18 parameters, a nested custom_fields object, and no output schema, the description does enough: it establishes partial-update scope, the status/record_type interaction, and the automation side effect, while leaving field-level detail to the fully documented schema. Only the return/error behavior is left unstated, which is a minor gap given no output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a genuine cross-parameter dependency not expressed in the schema: status_name may require record_type_name to succeed. That relationship is the kind of meaning the schema cannot convey, so it earns above baseline.

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

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

States a specific verb and resource ('Edit fields on an existing job') and enumerates the kinds of fields affected (status_name, address, sales rep, dates), which cleanly separates it from jobnimbus_create_job and jobnimbus_get_job. The trailing REST mapping (PUT /jobs/{jnid}) removes any ambiguity about what operation is performed.

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

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

Gives clear context for use (modifying an existing job), an explicit exclusion ('Cannot delete or archive'), and a conditional workaround (pass record_type_name alongside status_name if the status change is rejected). It stops short of naming the create/get siblings as alternatives, so it is clear but not fully routing.

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

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

Annotations only supply destructiveHint=true, so the description adds real value: "Only the fields you pass change" discloses PATCH-style partial-update semantics, and "Cannot delete" bounds the blast radius of the destructive hint. It says nothing about permission requirements for reassignment or what the response returns, which keeps it below a 5.

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

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

Three tight sentences: capability list first, then the two behavioral constraints, then the underlying endpoint. Nothing is redundant and the most important constraint is front-loaded.

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 11-parameter mutation with no output schema and fully documented inputs, the description covers the essential unknowns: partial-update scope, no deletion, and completion toggling. Missing only auth/actor caveats and result shape, which are minor here.

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

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

Schema description coverage is 100%, so every parameter including actor, priority, and the date fields is already documented. The description restates a few of them (is_completed true/false) without adding format or syntax detail beyond the schema; the 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 (Edit) and resource (an existing task) and enumerates the concrete edit surfaces: reschedule, title, priority, reassign, complete/reopen. An agent can distinguish it from create_task and get_task without opening any schema.

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

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

Gives clear context for when to use it (modifying an existing task) and an explicit exclusion ("Cannot delete"), plus the partial-update contract. It does not name a sibling alternative such as create_task for new tasks, so it stops short of a full routing rule.

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