jobnimbus

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

Annotations only declare destructiveHint=true, so the description carries the rest: it warns that workflow automations may fire (side effects beyond the record itself) and flags validation coupling to account settings, which prevents failed calls. It stops short of describing permissions/token scope 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?

Four short sentences, front-loaded with the purpose and the mandatory-input rule, then validation, then side effects, then the API endpoint. Every sentence earns its place with no repeated 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?

For a 23-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers identity requirements, required enums-like fields, external validation, and automation side effects. It omits what is returned (e.g., new contact id) and any duplicate-detection behavior, which keeps it just shy of complete.

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

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

With 100% schema coverage the baseline is 3, but the description adds a constraint the schema cannot express: the 'at least one of first_name/last_name/display_name/company' identity rule, plus the meaning of record_type_name as a workflow and status_name as a status within it. That is genuine added value over the minLength-only schema entries.

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+resource ('Create a contact') and pins the underlying operation ('JobNimbus: POST /contacts'), so it is immediately distinguishable from the create_job/create_note/create_task siblings. No ambiguity about what the tool produces.

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 real preconditions: at least one identity field (first_name/last_name/display_name/company), plus required record_type_name and status_name that must match account settings, with an explicit pointer to jobnimbus_get_account_settings. It does not, however, contrast with jobnimbus_update_contact (i.e., when to create vs. modify), so it falls short of full when/when-not coverage.

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

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

Annotations already flag destructiveHint=true, and the description adds real behavioral context beyond that: 'Workflow automations may fire' (a side effect) and that record_type_name/status_name 'must match the account settings' (a validation constraint). It stops short of describing the return payload, but adds meaningful value over the annotation.

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

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

Front-loaded with the action and required fields, then supporting detail, ending with the REST endpoint. Efficient overall, though the parenthetical examples make it slightly denser than needed.

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

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

For a 17-param creation tool with a fully documented schema, nested custom_fields, and no output schema, the description covers the required inputs, contact linking, side effects, and the underlying endpoint. An agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all 17 parameters and the baseline is 3. The description adds light semantics ('record_type_name (a job workflow, e.g. Residential)' and 'status_name (a status in it, e.g. Lead)') plus the account-settings match constraint, but does not materially extend the schema.

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

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

States a specific verb ('Create') and resource ('a job (project)') and maps clearly against siblings like create_contact, create_task, and update_job. An agent can tell immediately this creates a new job record rather than modifying one.

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 'Create a job', and it gives a nudge to link the homeowner via primary_contact_id, but it never states when to use this versus update_job or whether a contact must exist first. No explicit when/when-not or alternative routing is provided.

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 carry title and destructiveHint=true; the description discloses the default activity type and the underlying endpoint (POST /activities), which is modest extra context. It does not say what happens on a bad primary_id, whether the note is immediately visible, or why the operation is flagged destructive, and the admin-key requirement for 'actor' lives only in the schema. No contradiction with annotations.

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

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

Three short sentences, front-loaded with the action and target, then the default value, then the endpoint. The trailing 'JobNimbus: POST /activities.' is the weakest sentence but is compact and plausibly useful for traceability rather than padding.

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

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

For a simple create tool with a fully documented 5-parameter schema, no output schema, and a safety annotation already present, the description covers the essentials an agent needs to invoke it. Only minor gaps remain (no return/confirmation info, no explicit prerequisite that the referenced contact or job must exist).

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

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

Schema description coverage is 100%, so the schema already explains every parameter including the Defaults-to-Note behavior and the admin-key caveat for 'actor'. The description's mention of the record_type_name default essentially restates 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 precise verb and resource ('Add a note (activity entry) to a contact or job's activity feed'), immediately distinguishing it from jobnimbus_create_contact, create_job, create_task and from the read-side jobnimbus_list_activities. The parenthetical '(activity entry)' clarifies the underlying JobNimbus object so there is no ambiguity about what is created.

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?

Offers one piece of usage context: record_type_name defaults to Note and other activity types can be pulled 'from the account settings'. But it gives no when-to-use/when-not guidance, no prerequisites (e.g. that the target contact/job must already exist, or that actor requires an admin key), and never points to a sibling tool for related operations.

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 declare destructiveHint=true, but the description doesn't explain what is destroyed or what permissions are needed. It restates three required fields and the endpoint, adding no behavioral context (e.g., side effects, whether related_id must exist, rate limits). For a mutating create tool, this is 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?

Single efficient sentence plus endpoint, front-loaded with the core action and required fields. No redundant prose. Slightly cramped due to the parenthetical clauses, but 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 10-param mutation tool with no output schema, the description is minimally adequate. It covers required fields and endpoint, but omits return behavior, error conditions, and any prerequisite relationships (e.g., related_id must be an existing contact/job). Annotations only flag destructiveHint, leaving much unsaid.

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 fully documents all 10 parameters including units and constraints. The description adds only marginal field clarification (date_start as unix seconds, record_type_name example) that is already in 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+resource ('Create a task or appointment') and the API endpoint (POST /tasks). It differentiates from siblings like create_contact/create_job by calling out the 'appointment' variant and the record_type_name constraint. No explicit sibling routing, but purpose is 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?

No when-to-use/when-not-to-use guidance. It does not tell the agent whether to use create_task vs creating an activity, nor does it reference any sibling. It only restates requirements already implied by the schema's required array.

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 real context beyond that: it identifies the underlying API call (GET /account/settings) and explains that the returned values are the canonical enum strings create/update tools accept, which is behaviorally meaningful. It does not cover caching, auth scope, or whether the full payload can be large, so it stops 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?

Three sentences, front-loaded with purpose, then the motivating use case, then the narrowing parameter and API mapping. No filler, and the most decision-relevant information comes first.

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

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

With no output schema, the description does useful work by listing the configuration categories returned, and the low-complexity single optional parameter is fully explained. It lacks the shape/nesting of the response, but for a read-only settings fetch this is close to 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% and the single 'field' parameter is already documented with the same 'e.g. groups' example in the schema. The description reinforces rather than extends that semantics, 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 ('Fetch the account's configuration') and enumerates the concrete contents (contact/job workflows, statuses, task types, activity types, file types, lead sources). This clearly distinguishes it from the sibling list_*/get_* tools that return business records rather than configuration metadata.

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?

'Use it to find the exact record_type_name / status_name / source_name values the create and update tools need' explicitly ties the tool to the workflow that requires it and names the dependent tool families. The optional field parameter is also framed conditionally ('Pass field to get just one setting'), so both invocation modes are covered.

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 real value beyond that by listing the exact data returned (phones, email, address, workflow status, lead source, sales rep, custom fields) and citing the underlying REST endpoint, giving the agent a clear picture of the payload.

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

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

Two compact sentences, front-loaded with the core action and followed by the concrete return fields. No filler or redundancy.

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

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

For a single-parameter read tool with full schema coverage and annotations carrying the safety profile, the description supplies everything needed: what it fetches, the key required, and the fields returned. Nothing essential is missing.

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

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

Schema description coverage is 100% and the single jnid parameter is already documented as 'The contact's jnid (JobNimbus record id).' The description's 'by jnid' adds no format, source, or lookup detail beyond what the schema 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?

States a specific verb and resource ('Fetch a single contact by jnid') and even enumerates the returned fields, making the scope immediately clear. The word 'single' distinguishes it from the sibling list_contacts without needing to open either schema.

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

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

The required jnid parameter implies the caller must already know the contact's record id, which implicitly steers agents who only have a name to the list/search siblings. However, no alternative is named and there is no explicit when-to-use or when-not-to-use 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 declare readOnlyHint=true, so the safety profile is already covered. The description adds value beyond that by disclosing the returned content (line items, payments applied, totals), which matters because no output schema exists. It does not cover behavior for an invalid or missing jnid.

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 payload description first, the underlying endpoint second. No filler and nothing important buried.

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

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

For a single-record read with no output schema, the description usefully enumerates the returned fields and gives the backing endpoint. Only error/not-found behavior is unaddressed, a minor gap for this 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?

Only one parameter and schema coverage is 100%, so the schema already fully documents jnid. The description restates 'by jnid' without adding format or lookup semantics, which is the expected baseline when the schema 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?

States a specific verb (Fetch) plus resource (single invoice) and enumerates the returned payload (line items, payments applied, total, total_paid, due). This clearly separates it from the sibling jobnimbus_list_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?

Usage is implied by 'single invoice by jnid' versus the list sibling, and the required jnid signals when it can be called. However, it never explicitly names jobnimbus_list_invoices as the alternative for browsing, so the when-not condition must be inferred.

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 this is a safe read, so the annotation carries the safety profile. The description adds the returned field set, which is useful, but says nothing about error behavior for an invalid jnid, pagination, rate limits, or auth needs — modest added value against an 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?

Two tight sentences, front-loaded with the fetch action and its returned payload. Every clause earns its place, with the endpoint reference appended last.

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

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

For a single-parameter read tool with no output schema, listing the returned fields is a genuinely useful stand-in for the absent return spec. Only minor gaps remain (invalid-jnid behavior), and annotations cover the read semantics.

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 jnid parameter is documented there, so baseline is 3. The description restates that the job is fetched by jnid but adds no format, sourcing, or lookup guidance 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 by jnid) and enumerates the returned fields. The word 'single' implicitly distinguishes it from list_jobs, but it does not name the sibling to make the contrast explicit.

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

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

Usage is only implied: 'single job by jnid' suggests a lookup when the jnid is already known, contrasting with the list_jobs/update_job siblings. There is no explicit when-to-use or when-not statement, and no mention of what to do when the jnid 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=true, so the safe-read profile is covered; the description adds value by enumerating the returned attributes (title, type, start/end, priority, completion, owners, related records) and the backing endpoint, which is useful because there is no output schema. It omits error behavior (e.g., not-found handling), so it stops 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 compact sentences with the purpose front-loaded and no wasted words. The trailing 'JobNimbus: GET /tasks/{jnid}' is mildly redundant developer metadata 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 single-parameter read tool with annotations covering safety and no output schema, the description supplies the missing return-field overview, making it largely self-sufficient. A note on lookup failure behavior would make it fully complete.

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

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

Schema description coverage is 100%, and the schema already documents jnid as the JobNimbus record id. The description only restates 'by jnid' without adding format, validation, or example detail, so it sits at the baseline 3 where the schema 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?

States a specific verb (fetch) and resource (a single task/appointment) scoped by jnid, which implicitly separates it from the sibling list_tasks. The added parenthetical of returnable fields sharpens what 'task' means here. It doesn't explicitly name the alternative tool, keeping it just below a 5.

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

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

Usage is implied by 'single task ... by jnid', which signals this is the by-id lookup versus a listing tool, but no when/when-not condition or named alternative (jobnimbus_list_tasks, jobnimbus_get_job) is given. The agent must infer the choice from context.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest of the burden and does add value: it defines the record composition (notes + system events) and the return envelope {count, activity}, letting the agent anticipate entry types. It stops short of stating ordering defaults or volume characteristics, which the schema only partially covers.

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

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

Three short sentences, front-loaded with purpose, followed by scope and return shape, then the endpoint. No filler and nothing 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?

With no output schema, the description supplies the return shape {count, activity} and the entry semantics, and the schema fully documents all six parameters. Minor gap: no mention of pagination strategy or ordering defaults at the description level, though the schema covers those fields.

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 schema already documents from/size/filter/sort/related_id in detail, including the from + size pagination rule and filter examples. The description only reiterates related_id as a contact-or-job scope, so it adds marginal meaning over structured data.

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

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

States a specific verb ("List") and resource ("activity entries"), and usefully defines what that bucket contains — "notes plus system events such as status changes and record creation" — plus the backing endpoint GET /activities. It does not explicitly contrast itself with sibling note/task tools, so sibling differentiation is left implicit.

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

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

"Optionally for one contact or job (related_id)" implies the scoped and unscoped modes, which is enough to pick the call for a contact/job timeline. However, no alternative tool is named and there is no guidance on when to prefer a filtered query versus a broad listing.

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 by stating default ordering (newest first) and the response envelope {count, results}. It stops short of describing pagination limits or filter failure behavior, but adds meaningful value beyond the annotations.

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

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

A single dense sentence front-loads the core action and scope, then appends the filter capability, return shape, and backing endpoint with no filler. Every clause earns its place.

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

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

With no output schema, the description usefully discloses the return shape and a nested-object filter isn't explained, but the schema's 100% coverage and rich examples carry that load. For a read-only list tool, this is nearly complete, missing only rate/pagination caveats already present in 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%, so every parameter (from, size, filter, sort_field, sort_direction) is already documented in the schema with examples and defaults. The description only reinforces the filter style and default sort, adding no syntax or semantics 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 (List) and resource (contacts) plus the record types covered (customers, leads, adjusters, subcontractors), and notes default ordering. It does not name the sibling it should be chosen over (jobnimbus_get_contact) for single-record lookups, so it is clear but lacks explicit sibling differentiation.

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

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

Mentions that filtering is optional and uses an ElasticSearch-style query, which implies how to narrow results, but gives no when-to-use guidance (e.g., use get_contact when a single jnid is known) or exclusions. 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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description clears it by disclosing the return envelope {count, results} and clarifying that count is the account total rather than the page size — a genuinely non-obvious behavior. It also maps to the underlying GET /v2/estimates endpoint. Rate limits or default page size are left to the schema.

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

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

Two tightly packed sentences: the first enumerates returned fields, the second covers the return envelope and the endpoint mapping. No filler, and the most decision-relevant content (what the tool returns) 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?

With no output schema, the description responsibly explains the return shape and disambiguates count as an account-wide total, which is exactly the kind of thing an agent would otherwise misread. What is missing is modest: no note on ordering, empty-result behavior, or default page size (though the schema covers the latter).

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 'from' and 'size' are already fully documented, including the pagination formula and the fact that this wrapper defaults to 25 rather than the API's 1000. The description adds nothing about either parameter, 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 estimates") and enumerates the fields present in each record — number, status, line items, subtotal, tax, total, margin, e-sign state, related job/contact. That is far more informative than the title alone. Sibling differentiation is implicit via the resource name rather than stated (no contrast drawn with list_invoices or list_jobs), which keeps it from 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, and no alternative tool is named. The only usage signal is the resource name itself, which an agent would infer anyway. Nothing tells the agent how this differs from jobnimbus_list_invoices or when to prefer a get_* tool for a single record.

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 genuinely useful behavioral context beyond that: 'Metadata only; file bytes are not downloaded' tells the agent it cannot retrieve file contents, and the return shape {count, files} is disclosed.

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

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

Two tight sentences, front-loaded with purpose and returned fields, then behavior and return shape. Every clause carries information with no filler.

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

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

For a read-only list tool with no output schema, the description covers the returned fields, the metadata-only limitation, the optional scoping, and the return envelope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so pagination, filter, sort and related_id are all already documented in the schema. The description only restates related_id's single-record scoping, adding little beyond the structured fields. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List file attachments') and enumerates the returned fields (filename, content type, size, file type, contact/job). It is the only file-oriented tool among the siblings, so the scope is unambiguous and an agent can distinguish it from the contact/job/task listers.

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 the scoping option ('optionally for one record (related_id)'), which is the main usage decision for this tool. It does not name when-not-to-use or alternatives, but no sibling offers an equivalent file-listing capability, so the missing exclusions are minor.

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 earns credit for disclosing the return envelope {count, results} and clarifying that count is the account total rather than the page length — a genuinely useful distinction an agent would otherwise misread. It does not cover auth or rate-limit behavior, but for a read-only list tool this is solid added context.

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

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

Two sentences, front-loaded with the resource and returned fields, followed by the return shape and endpoint. No filler and 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?

There is no output schema, so the description correctly compensates by describing the return envelope and the meaning of count. Combined with 100% parameter documentation for this simple 2-param read tool, an agent has enough to call it correctly; only the paging-default nuance lives solely in 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 coverage is 100%, so from/size are fully documented with pagination semantics in the schema itself. The description adds nothing about parameter units, defaults, or paging strategy, 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 invoices') and enumerates the fields returned plus the endpoint (GET /v2/invoices). It does not explicitly distinguish itself from the sibling jobnimbus_get_invoice, but the list-vs-single-resource distinction is inferable from the name pairing.

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

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

Usage is implied by the list semantics and the presence of jobnimbus_get_invoice as a sibling, but the description never states when to use this over get_invoice or how it relates to list_estimates/list_jobs. 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: default sort is newest-first, the response envelope is {count, results}, and it hits GET /jobs. It does not mention pagination ceilings (left to the schema), so it stops 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 compact sentences plus a short return/endpoint note; the core purpose and ordering default are front-loaded and every clause conveys information. No filler or redundancy.

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

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

With no output schema, the description usefully discloses the return envelope {count, results} and the endpoint. Filter examples and default ordering are covered, though pagination limits and whether filtering is server-side versus client-side are left 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%, so every parameter is already documented in the schema (filter format, from/size semantics, sort defaults). The description restates the filter shape with one status example and explains what related_id does, but adds no syntax or constraints beyond the schema, landing at the baseline.

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

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

States a specific verb and resource ('List jobs (projects)'), names the default ordering ('newest first'), and identifies the backing operation (GET /jobs). An agent can immediately distinguish this from jobnimbus_get_job (single record) or jobnimbus_create_job (write) 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?

It explains how to filter ('by status ... or by the related contact via related_id'), which implies usage, but never states when to prefer this over sibling list tools (list_contacts, list_activities) or over jobnimbus_get_job. No explicit when-not guidance 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?

The readOnlyHint annotation already establishes a safe read profile. The description goes beyond that by disclosing the return envelope ('Returns {count, results}'), which matters because there is no output schema, and by mapping to the underlying GET /tasks endpoint. It does not mention pagination limits or auth needs, but for a read-only tool that is a minor gap.

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?

Single compact burst of front-loaded information: purpose, scoping options, filter example, return shape, endpoint. Every clause earns its place and nothing is padded.

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

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

With no output schema, the description usefully declares the {count, results} return shape, and the filter/related_id/pagination semantics live in the schema. What is missing is guidance on default result volume or how count relates to pagination, but the definition is sufficient to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by supplying a task-specific filter example ({'must':[{'term':{'is_completed':false}}]}) that goes beyond the generic examples in the schema, and it restates related_id's contact/job scoping in prose.

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 tasks and appointments') and clarifies the scope includes appointments, which helps distinguish it from list_activities or list_contacts. However, it never explicitly differentiates itself from sibling list tools, so an agent must infer the routing from the resource name alone.

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

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

It implies two usage modes - scope by related_id or apply a filter - and gives a concrete filter example for open tasks, which is helpful context. It does not state when to prefer this over list_activities or get_task, nor any prerequisite/constraint on when filtering is required.

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 this is a safe read; the description adds the returned field list and the underlying endpoint (GET /account/users). It says nothing about pagination, rate limits, or ordering, so it adds only moderate context beyond the annotation.

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

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

Two tight sentences plus an endpoint reference; the payload shape is front-loaded and nothing is padded or repeated.

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 parameterless list tool with no output schema, listing the returned fields plus the endpoint makes it essentially complete. The only gap is the absence of pagination/result-size 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?

Zero input parameters, so per the baseline the description carries no parameter burden. The note about which downstream parameters consume the returned id is a helpful cross-tool pointer even if not a parameter per se.

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)') and even enumerates the returned fields (name, email, id, active). No sibling tool lists users, so confusion risk is nil, and an agent knows exactly what it gets back.

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 line 'The id is what owners, sales_rep and owner_ids take' tells the agent when this tool is needed — as an ID lookup feeding other tools' parameters. It lacks an explicit when-not-to-use or alternative-tool clause, but the usage context is clear.

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?

Goes well beyond the destructiveHint annotation: it discloses partial-update semantics ('only the fields you pass change'), a real side effect ('Changing status_name moves it along its workflow (automations may fire)'), and a scope limit ('Cannot delete or archive'). These are the behavioral traits an agent most needs before mutating a record.

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

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

Three tight sentences: behavior first, side effect second, constraint third, with the API endpoint as trailing metadata. Every sentence earns its place and the highest-value fact 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 a 24-parameter mutation tool with a nested custom_fields object and no output schema, the description covers the essential behavior and side effects. The remaining detail (per-field formats, response shape) is carried by the schema and, appropriately, does not need restating since 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 meaning the schema does not: the partial-update contract for all fields and the workflow effect of status_name. This elevates it above the baseline.

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

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

States a specific verb (edit) and resource (an existing contact), and the qualifier 'existing' differentiates it from jobnimbus_create_contact and jobnimbus_get_contact. An agent can tell what it does 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?

Gives clear context (edit fields on an existing contact) and an explicit exclusion ('Cannot delete or archive'), which steers away from delete/archive operations. It stops short of naming alternatives like jobnimbus_create_contact for creating records, so it is a strong 4 rather than a full 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?

The only annotation is destructiveHint=true, so the description carries the behavioral burden and delivers: partial-update semantics ("Only the fields you pass change"), side effects ("Automations may fire"), an error-recovery rule for status changes, and an explicit negative scope (no delete/archive). This is well beyond what the annotation provides.

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

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

Four tight sentences front-load the operation and its partial-update behavior, then layer caveats and the endpoint. Every clause carries information an agent would otherwise have to guess; no filler or restatement of the title.

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

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

For an 18-parameter mutation tool with only a destructiveHint annotation and no output schema, the description covers side effects, partial-update mechanics, failure handling, and limits. It could say a bit more about the response/permission context (e.g., that maestro result shape or actor requirements for the write), so it is strong but not exhaustive.

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 cannot: the status_name + record_type_name coupling on rejection and the fact that unspecified fields are left untouched. It also flags custom_fields quirks (is_active/is_archived ignored) consistent with the schema's own note.

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 ("Edit fields on an existing job") and enumerates concrete examples of the fields it edits (status_name, address, sales rep, dates). It is clearly distinguishable from the sibling write tools jobnimbus_create_job and jobnimbus_update_contact, which target creation or a different resource.

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 real in-operation guidance: pass record_type_name alongside status_name if the status change is rejected, and the tool "Cannot delete or archive," which excludes a class of use. It does not explicitly name alternatives (e.g., use jobnimbus_create_job for new records), so a small routing gap remains.

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; the description adds the key behavioral facts that only passed fields change (partial update), that deletion is impossible, and the is_completed true/false reopen semantics, plus the URL verb. It does not describe response shape or permission requirements beyond what the schema's actor field already says.

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 that front-load the capability list, then the partial-update and no-delete constraints, ending with the endpoint. No wasted verbiage.

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 tool with no output schema, the description covers the important semantics (partial update, no delete, completion toggle) and annotations cover the mutation risk. It could say more about the actor/admin requirement and any owner-assignment implications, which live only in 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%, so all 11 parameters are already documented in the schema. The description only restates is_completed semantics and the set of editable fields, adding little beyond the structured data; 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 ('Edit an existing task') and enumerates the actual edit dimensions (reschedule, title, priority, reassign, complete/reopen), plus the underlying endpoint PUT /tasks/{jnid}. An agent can separate this from create_task and get_task 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?

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

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