insightly

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

The description adds the concrete backing endpoint (POST /<Object>/{id}/Notes), which is useful behavioral context beyond the single destructiveHint annotation. However it is silent on permissions/scopes needed, whether the record id must already exist, and whether repeated notes are permitted or deduplicated — a gap for a mutating call.

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

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

Two short clauses, front-loaded with the action and the affected entities; nothing is redundant or padded. The endpoint reference is compact and informative.

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

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

For a four-parameter, fully schema-documented tool with no output schema, the description covers the action, target entities and endpoint. It leaves the response (e.g. the created note id) and error/permission behavior unstated, which is a minor but real gap given there is no output schema to fall back on.

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

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

Schema description coverage is 100%, so the schema already documents id, title, body (HTML allowed) and the object enum. The description's '(title + body)' only restates schema content and adds no format, length, or constraint detail beyond it. 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 ('Add a note (title + body)') and enumerates the exact parent record types it can attach to (Contact, Organisation, Lead, Opportunity, Project). No sibling tool deals with notes, so an agent can distinguish this from the create_*/update_* family at a glance.

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

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

The description says what can be attached where, but gives no when-to-use guidance: no mention of prerequisites (e.g. the record must already exist), no note about alternatives such as insightly_create_task or insightly_list_record_activity for related activity. Usage is only implied by the verb.

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

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

Annotations provide only destructiveHint=true, so the description carries most of the burden for a mutation tool. It tells the agent the record is created via POST /Contacts but omits auth/permission requirements, whether duplicates are merged or rejected, what the response returns, and what happens to unrelated fields — significant omissions for a create.

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 core action and the required-field constraint, with no filler. It is efficient, though the trailing endpoint note is of marginal value to an agent.

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

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

For an 18-parameter mutation with no output schema and only a destructiveHint annotation, the description is far too thin — it explains nothing about return values, error conditions, or how the many optional fields interact. An agent calling this correctly must rely almost entirely on 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 72%, above the baseline threshold, so the schema documents most parameters itself. The description only repeats that first_name is required, adding no format, validation, or usage detail beyond what the schema already states.

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 even names the underlying endpoint (POST /Contacts), which pins the action unambiguously. It does not, however, distinguish itself from siblings like insightly_create_lead or insightly_update_contact, so an agent must infer from the name alone.

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

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

No guidance on when to create a contact versus creating a lead or updating an existing contact, and no prerequisites or deduplication caveats. The only condition given is that first_name is required, which is already enforced by the schema.

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

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

Annotations give only destructiveHint=true, so the description carries the rest. It discloses a genuinely non-obvious behavior: Insightly's API also requires lead_status_id and lead_source_id even though the schema marks only last_name required, plus the underlying POST /Leads call. Auth requirements and failure behavior are not 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?

Three compact sentences with the required-field constraint front-loaded and no filler. The API endpoint is arguably redundant but costs almost nothing.

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 create tool with 38% schema coverage and no output schema, the description covers the highest-risk gotcha (hidden required ids) but leaves most parameters and any post-create behavior unexplained.

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 only 38% across 24 params, so the description must compensate, and it does so for the critical case (the two ids driven by the API-level required fields and their lookup tools). The remaining ~22 params, including owner_user_id, responsible_user_id and custom_fields, get no further clarification.

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

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

States a specific verb and resource ('Create a lead') and names the single required field inline. It doesn't differentiate itself from insightly_create_contact, but the resource is unambiguous.

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

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

Useful routing guidance is given for the id fields (get valid ids from insightly_list_lead_statuses / insightly_list_lead_sources), but there is no guidance on when to create a lead versus a contact or opportunity, nor any prerequisite/ordering advice.

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 destructiveHint=true, which tells the agent this writes state; the description adds nothing beyond that — no note on permissions, side effects, or what happens on duplicate names. The required-field remark is already in both the schema and the annotations' title.

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 required field. The trailing 'Insightly: POST /Opportunities.' is low-value API trivia but costs little.

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

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

For a 13-parameter mutation tool with no output schema, the description says nothing about what is returned (e.g. new opportunity id), error behavior, or which optional fields matter. The schema carries most weight, but the description leaves the agent without any operational context.

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 85%, so the schema already documents bid_type, bid_amount, probability, custom_fields, forecast_close_date format, etc. The description only restates that opportunity_name is required, adding no semantics beyond the structured fields.

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

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

States a specific verb+resource ('Create a sales opportunity') and names the required field, clearly distinguishing it from the create_* siblings for other record types and from update_opportunity. It does not explicitly route the agent between create/update, but the verb 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as insightly_update_opportunity for existing records. The only usage signal is that opportunity_name 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?

The only annotation is destructiveHint=true, which the description neither confirms nor elaborates. Nothing is said about what is created, what the response contains, whether the operation is idempotent, or what auth/fields are required for a 12-parameter write.

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, with zero filler. It is efficiently written, though the brevity borders on under-specification for a 12-parameter tool.

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

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

For a 12-parameter mutation tool with no output schema, partial schema coverage, and only a destructiveHint annotation, the description omits required-field guidance, return shape, and any behavioral context. It is not sufficient to call the tool 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 description coverage is only 42% across 12 parameters, and the description adds no parameter meaning at all — no mention of required organisation_name, custom field syntax, or the billing address fields. It fails to compensate for the coverage gap.

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

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

States a clear verb and resource ('Create an organisation (company)') and maps it to the underlying API endpoint POST /Organisations. The resource name itself distinguishes it from sibling create tools like create_contact and create_lead, though it doesn't explicitly contrast them.

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

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

There is no guidance on when to use this tool versus alternatives (e.g. create_contact, update_organisation) or prerequisites such as required fields or permissions. Usage is only implied by the name.

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

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

The description adds real behavioral value beyond the schema: it discloses that owner_user_id is backfilled from the API key's own user via GET /Users/Me and that completed defaults to false, which an agent could not infer from the schema. It also names the underlying endpoint (POST /Tasks). It does not address rate limits or what happens on partial/invalid input, keeping it below 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 compact sentences with the required-field constraint front-loaded and no filler. The trailing 'Insightly: POST /Tasks' endpoint note is slightly redundant with the surrounding prose but is not wasteful enough to drop the score further.

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

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

For a 14-parameter creation tool with no output schema and no meaningful annotations beyond destructiveHint, the description covers the required field, the two hidden defaults, and the target endpoint. Remaining gaps (return shape, error behavior) are minor; no output schema exists to document returns, so it need not.

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

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

Schema description coverage is already 93%, so the baseline is 3; the description earns a bump by documenting server-side defaulting behavior for owner_user_id and completed that the schema does not state. It adds no format detail for date or custom-field parameters, so it is not 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?

States a specific verb and resource ('Create a task') and flags the one required field up front, so it is clearly distinguishable from the list of insightly_create_* siblings. It does not explicitly contrast with insightly_update_task, which is the nearest sibling, so it falls short of a 5.

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

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

There is no guidance on when to use this versus insightly_update_task or insightly_add_note, and no prerequisites or permissions noted. The sentence about OWNER_USER_ID/COMPLETED is API mechanics rather than usage routing, so an agent gets no selection help.

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 structurally; the description adds that the call is 'cheap' (low cost/no heavy side effects) and enumerates the returned identity fields. It does not mention rate limits or pagination, but for a zero-parameter read there is little else to disclose.

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 purpose and return values, ending with the API endpoint. Every clause carries weight with no 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 present, the description compensates by naming the returned fields (USER_ID, name, email, admin flag). Combined with the auth context and endpoint, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify, and it correctly adds no spurious parameter discussion.

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 (the user the API key belongs to), plus the exact returned fields and the underlying endpoint (GET /Users/Me). This distinguishes it from the sibling insightly_list_users, which lists all users rather than the key's own identity.

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

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

Explicitly frames two use cases: confirming the API key/pod pairing and obtaining your own id for owner fields. It implies the distinction from list_users but never names an alternative explicitly, so it falls just short of a full when/when-not treatment.

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 adds real value by disclosing the payload shape: the returned record includes 'custom fields, tags and links', which matters since no output schema exists. It stops short of 5 only because it says nothing about missing-id behavior or errors.

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 fetch behavior front-loaded; the trailing 'Insightly: GET /<Object>/{id}' is largely redundant with the prose, but it costs little and confirms the underlying call.

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

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

For a two-parameter read with full schema coverage and no output schema, the description covers the return payload (custom fields, tags, links), which is the main missing piece. Error and not-found behavior remain unaddressed, keeping 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 the object enum is fully documented in the input schema, so baseline 3 applies. The description's 'by id' and record-type list merely restate what the schema already provides.

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

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

States a specific verb and resource: 'Fetch a single ... by id' and enumerates the eight supported record types, which distinguishes it from insightly_list_records and insightly_search_by_tag. The differentiation is implicit (via 'single' + 'by id') rather than an explicit contrast, so it stops short of a 5.

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

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

Usage is only implied by the 'by id' phrasing — an agent can infer it is the lookup-by-identifier counterpart to the list/search tools, but the description never states when to prefer it over insightly_list_records or insightly_search_by_tag, nor any prerequisites.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying endpoint (GET /LeadSources) and the return shape (ID and name), which is modest extra value, but says nothing about ordering, pagination behavior, or whether the list is user-scoped.

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

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

A single tight sentence that front-loads the action and resource before the parenthetical fields and endpoint. Nothing is padded, though the endpoint reference adds little for an agent that cannot call the API directly.

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

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

For a zero-parameter, read-only enumeration with no output schema, the description supplies the essential facts: what is listed and which fields come back. Pagination semantics are left to the schema, and ordering is unspecified, but nothing critical is missing.

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

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

Schema description coverage is 100%, with top (1-500, default 100) and skip fully documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the lead sources defined in the instance') and even names the fields returned (LEAD_SOURCE_ID, name). It is distinguishable from siblings like insightly_list_lead_statuses by its resource, though it never explicitly contrasts itself with them.

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, no prerequisites, and no mention of alternative tools. The agent must infer from the name that this is a reference-data lookup used to resolve a lead source ID.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the endpoint (GET /LeadStatuses) and the instance-scoped nature of the data, but says nothing about result volume, paging behavior, or ordering beyond what the schema already carries.

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 tightly-packed sentence plus the endpoint reference. The purpose and return fields are front-loaded 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?

There is no output schema, and the description usefully substitutes by naming the returned fields and the underlying endpoint. Annotations cover read-only safety and all three parameters are documented, so the only real gap is the absent usage/routing guidance.

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 top, skip, and include_converted are fully documented in the schema. The description adds no parameter meaning of its own, which is the baseline 3 case 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 the lead statuses defined in the instance') and even enumerates the returned fields (LEAD_STATUS_ID, name, type). It is clearly distinguishable from the similar list_lead_sources/list_pipelines siblings by resource name, though it never explicitly contrasts them.

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 guidance, no prerequisites, and no mention of alternatives. An agent choosing between this and insightly_list_lead_sources or insightly_list_pipelines gets no routing help from the description.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the API endpoint (GET /Pipelines) and the shape of the returned records (PIPELINE_ID, name, opportunities vs projects), which partially compensates for the absent output schema, but discloses nothing about auth, rate limits, or paging behavior.

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

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

One sentence plus a short endpoint reference; the key content (what is listed and what fields come back) is front-loaded with no filler. The endpoint citation is marginal but not 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, read-only, two-parameter list call with no output schema, the description supplies enough: the resource, the returned field names, and the underlying endpoint. Only paging semantics and the absence of filtering go unaddressed, which the schema largely covers.

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 both top and skip fully documented in the schema (including the API default of 100), and the description does not repeat or extend them. Baseline 3 is appropriate when the schema carries the parameter burden.

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 pairs a specific verb (List) with a specific resource (sales and project pipelines) and enumerates the fields returned, which implicitly separates it from the similarly named insightly_list_pipeline_stages. It never explicitly names that sibling, but the resource is unambiguous.

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

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

Usage is only implied: an agent can infer this is the reference-lookup call for pipeline IDs before creating opportunities or projects, but the description states no when-to-use condition, no exclusions, and no alternative. With no filtering parameters, there is little routing guidance to give.

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 a safe read, so the bar is lower. The description adds only the underlying endpoint (GET /PipelineStages); it says nothing about pagination behavior, default result counts, or whether the list is account-scoped.

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

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

A single compact sentence front-loads the action and returned fields, then appends the motivating use case and 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?

With no output schema, the description usefully lists the returned fields and the mapping use case, and pagination is covered by the top/skip schema entries. Only the staleness/scope of the stage list is unaddressed, a minor gap for a simple read tool.

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

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

Schema description coverage is 100% (top and skip are both documented in the schema), so the schema carries parameter semantics. The description contributes no additional parameter guidance, making the baseline 3 appropriate.

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

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

States a specific verb and resource (list pipeline stages) and enumerates the fields returned (STAGE_ID, PIPELINE_ID, name, order), which is more than a restated name. It does not explicitly distinguish itself from the sibling insightly_list_pipelines, so an agent must infer the boundary.

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 concrete use case — mapping an opportunity's or project's STAGE_ID to a stage name — which tells the agent when the tool is relevant. It stops short of naming alternatives (e.g., insightly_list_pipelines) or stating exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lowered. The description adds the underlying API route (GET /<Object>/{id}/Notes | Tasks | Events), but says nothing about count_total behaviour, paging semantics, or response shape beyond what the schema 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?

One dense sentence with the core scope front-loaded, followed by a short endpoint mapping. The endpoint line is useful for developer-facing agents, though the parent-type and kind enumerations mildly duplicate the schema enums.

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 8 parameters, no output schema, and full schema coverage, the definition covers purpose, scope and API route adequately. Minor gaps remain around pagination/response expectations, but nothing critical for 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%, so every parameter (id, kind, top, skip, brief, object, count_total, updated_after_utc) is documented in the schema itself. The description only re-states the enum values (parent types and activity kinds) without adding format or interaction detail, so baseline 3 applies.

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

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

States a specific verb ('List') and resource (Notes/Tasks/Events attached to one record) and enumerates the exact parent types supported. The phrase 'the activity history of that record' pins down the scope so an agent can distinguish it from insightly_get_record or insightly_list_records 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?

Usage is implied by 'attached to one Contact, Organisation, Lead, Opportunity or Project', which tells the agent a parent id is needed. However, it never states when to choose this over a sibling like insightly_get_record or insightly_list_records, and offers no exclusions or prerequisites.

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

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

readOnlyHint=true already covers the safety profile, but the description adds real behavioral context beyond annotations: which endpoint is invoked under which parameter combination, and the pairing constraint on field_name/field_value. It omits pagination/return-shape behavior, keeping 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?

Three dense sentences, front-loaded with the resource and record types before the filtering mechanics. Every clause carries information, though the examples list is slightly 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 an 8-parameter read tool with no output schema, the description covers purpose, both query modes, and field-name syntax adequately. Return-shape details (e.g. what count_total produces) are delegated to the schema, which is acceptable 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 coverage is 100%, so baseline is 3, but the description adds value the schema lacks: the UPPER_SNAKE field-name convention with concrete examples (EMAIL_ADDRESS, LAST_NAME) and custom-field syntax (Industry__c), plus the both-or-neither rule for field_name/field_value.

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

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

States a specific verb and resource and enumerates exactly which record types are supported (Contacts, Organisations, Leads, etc.). It also distinguishes the two operational modes — filtered search vs plain list — which no sibling does.

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?

Clearly explains the condition that selects each mode: field_name+field_value (required together) or updated_after_utc triggers /Search, otherwise plain GET. It does not, however, name alternatives such as insightly_search_by_tag or insightly_get_record for single-record lookups, so the when-not guidance is incomplete.

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. Beyond that the description confirms the REST endpoint but says nothing about what a user record contains (the very IDs it claims to resolve), pagination behavior, or response shape. With annotations carrying the safety burden, this is adequate but thin.

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

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

Two short clauses, front-loaded with the verb+resource, then the operational motivation, then the endpoint. No filler; every fragment 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?

There is no output schema, so the description should carry some of the return-value burden; it only says it lists users without indicating that records expose the user IDs needed to satisfy the stated purpose. For a simple read with 100% schema coverage this is passable but incomplete.

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 all three parameters (top, skip, count_total) are documented in the schema including the count_total response-shape change. The description adds no parameter guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('List the users in the Insightly instance') and adds the underlying endpoint GET /Users, so the operation is unambiguous. It partially differentiates from siblings by implying this is the ID-resolution source, but never contrasts itself with insightly_get_current_user, which an agent could easily confuse it with.

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 concrete reason to call it — resolving OWNER_USER_ID / RESPONSIBLE_USER_ID before writes — which is real, actionable context. It stops short of an explicit alternative ('use get_current_user for the caller's own identity'), so the routing to siblings is left partly to inference.

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

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

readOnlyHint=true in annotations already tells the agent this is a safe read, so the bar is lower. The description adds the underlying REST endpoint (GET /<Object>/SearchByTag?tagName=), which is mildly useful, but says nothing about pagination behavior beyond what the schema already exposes.

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 supported object types and the tag criterion, with the endpoint as a terse second clause. 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 what is searched and how it is scoped, and the schema carries paging/brief/count_total semantics. It could say a bit more about the returned collection (e.g. that count_total alters the response shape), but it is nearly complete.

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

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

Schema description coverage is 100%, so the six parameters (tag, top, skip, brief, object, count_total) are fully documented in the schema including defaults and ranges. The description adds no parameter meaning beyond restating the tag/object scope, 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 (List) and resource (Contacts, Organisations, Leads, Opportunities, Projects) plus the scoping filter (carrying a tag). The tag filter implicitly separates it from insightly_list_records, though no sibling is named explicitly to reinforce the distinction.

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 tag-scoped framing implies when to reach for it (retrieving records by tag rather than listing all records), but there is no explicit when-to-use, when-not-to-use, or named alternative such as insightly_list_records.

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 carries real weight and does add value with the 'only fields you pass are changed (v3.1 partial update)' clarification, which is genuine behavioral context. However, it does not disclose what happens to untouched fields' risk profile, permission/auth needs, or how the destructive nature manifests (e.g., overwriting existing values), leaving meaningful gaps.

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 core action and the partial-update rule. The trailing API-path sentence ('Insightly: PUT /Contacts with CONTACT_ID') is somewhat redundant implementation detail, keeping it just short of a 5.

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 19-parameter mutation with no output schema and only a destructive annotation, the description covers the key mutation semantics (partial update) but omits auth/permission expectations, destructive-behavior detail, and confirmation of which fields are required (deferred entirely to the schema). Adequate but with clear gaps.

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

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

Schema description coverage is 74%, so the schema already documents most of the 19 parameters. The description's partial-update statement implicitly clarifies that omitted parameters are left unchanged, which is useful, but it adds no syntax or format detail for individual parameters 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+resource ('Update a contact') and adds the partial-update semantics plus the underlying API call (PUT /Contacts with CONTACT_ID), making the operation unambiguous. It does not explicitly distinguish itself from the create_contact sibling, but the update verb does most of that work.

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

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

There is no explicit when-to-use guidance or comparison to siblings like insightly_create_contact or insightly_update_lead. The partial-update note implies the tool targets existing records, but nothing tells the agent when this is preferable to an alternative, nor are prerequisites (e.g., a valid contact_id) called out.

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

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

Annotations only declare destructiveHint=true, leaving most behavioral burden to the description. The partial-update semantics ('only the fields you pass are changed') is a genuinely useful disclosure, but it omits permissions/scopes, whether omitted fields are preserved or nulled, and whether the operation is reversible. Not contradictory to the destructive hint, just incomplete.

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 filler: purpose, mutation semantics, underlying endpoint. Nothing is padded or 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 25-parameter update tool with 40% schema coverage, no output schema, and only a destructiveHint annotation, the description is far too thin. An agent cannot tell which of the many fields are required beyond lead_id, how statuses/sources/owners are referenced, or what the response confirms.

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 only 40% across 25 parameters, so the description must compensate and largely does not. It never enumerates which fields are settable or clarifies the custom_fields null-clearing behavior, addressee IDs, or the difference between owner/responsible user id — all of which live only in the schema (or nowhere).

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

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

States a specific verb+resource ('Update a lead') and adds the crucial partial-update rule ('Only the fields you pass are changed'). It does not explicitly contrast with siblings like insightly_create_lead or insightly_update_contact, so it stops short of 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?

The description implies mutation of an existing lead but gives no when-to-use guidance, no prerequisites, and no alternative routing (e.g., create_lead vs update_lead vs update_contact). Nothing tells an agent when this tool is the right choice.

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 destructiveHint=true already declared, the description adds real value by stating that unchanged fields are preserved (partial PATCH-style semantics) and naming the underlying endpoint. It still omits permission/auth requirements, reversibility, and whether the updated record is returned, so it only partially lifts the behavioral burden.

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 a compact endpoint reference; the action and the partial-update rule are front-loaded 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 14-parameter mutation tool with no output schema, the description covers intent and update semantics but says nothing about the response, error behavior, required vs optional handling, or permission prerequisites. Adequate but leaves noticeable gaps an agent would have to infer.

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 86%, so the schema already documents nearly every parameter (currency, dates format, probability 0-100, custom fields). The description only echoes field families in prose, adding no format or constraint 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?

Clear verb+resource ('Update an opportunity') plus the specific field families affected (value, probability, dates, owner, details). It is easily distinguished from insightly_create_opportunity, but it never names siblings or scope boundaries explicitly.

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

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

Usage is implied by 'Update', and 'Only the fields you pass are changed' usefully signals partial-update semantics. However there is no when-to-use/when-not guidance, no prerequisite call (e.g. needing an existing opportunity_id), and no routing to an alternative tool.

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

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

Annotations already declare destructiveHint=true, so the mutation risk is covered structurally. The description adds genuine value with the PATCH-style semantics ('Only the fields you pass are changed'), but omits any auth requirements, side effects, or consequences of the destructive update.

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 no wasted words; the partial-update semantic and API endpoint are stated plainly. The API endpoint detail is marginally useful but does not bloat the text.

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

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

For a 13-parameter destructive mutation with no output schema and 46% schema coverage, the description is too thin. It does not clarify how custom_fields, owner_user_id, or the address fields behave, nor what the response returns after an update.

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 only 46%, so the description carries a compensation burden it does not meet. Beyond naming ORGANISATION_ID in the API call string, it provides no field-level meaning for the 13 parameters, leaving many undocumented in both schema and description.

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 ('Update an organisation') and clarifies the underlying API operation ('PUT /Organisations with ORGANISATION_ID'). It implicitly separates itself from the sibling insightly_create_organisation, but does not explicitly name or contrast with any sibling.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives like insightly_create_organisation or insightly_get_record. The partial-update note hints at the edit workflow but stops short of routing guidance.

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

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

Annotations only provide destructiveHint=true, so the description meaningfully adds the partial-update semantic (only supplied fields change), which is non-obvious given the stated PUT endpoint that would normally imply full replacement. It still omits permission requirements, whether omitted fields are cleared, and any rate/conflict behavior, but the key mutation contract is disclosed.

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

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

Three short sentences, front-loaded with the action and scope, and the partial-update rule is placed immediately after. The trailing "Insightly: PUT /Tasks with TASK_ID" is largely redundant with the task_id parameter and the tool name, a minor 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 15-parameter mutation tool with no output schema and only a destructiveHint annotation, the description plus the 93%-covered schema give an agent enough to invoke it correctly. It does not address return values, error behavior, or that clearing a field requires an explicit value (the schema hints at this via custom_fields null), leaving a small gap.

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

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

Schema description coverage is 93% with 15 parameters, so the schema already carries essentially all parameter meaning, including date formats and the note that the instance defines valid STATUS values. The description only renames a few fields colloquially (e.g. "assignee" for responsible_user_id) without adding format or constraint detail, so baseline 3 applies.

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

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

States a specific verb (update) and resource (task) and enumerates the common fields an agent would touch (completed, due date, status, assignee, details). The resource name itself separates it from the update_contact/update_lead/update_opportunity siblings, but the description never explicitly contrasts with insightly_create_task or the other update tools.

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

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

"Only the fields you pass are changed" is useful partial-update guidance that steers the agent toward passing a minimal payload, but there is no explicit when-to-use/when-not-to-use statement and no reference to alternatives such as create_task or get_record for reading current values before an update.

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