Insightly MCP by usefulapi

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

Annotations already declare destructiveHint=true, so the write nature is covered by structured data. The description adds the underlying API endpoint, which is useful context, but says nothing about auth needs, whether the note is appended vs. replaces anything, or rate limits. It does not contradict 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 compact sentences, front-loading what is added and to what, followed by the endpoint. Every clause earns its place; nothing is redundant or padded.

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

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

For a simple four-parameter write tool with complete schema coverage and a safety annotation, the description supplies enough to invoke correctly. It is slightly thin on the object/id pairing and HTML body handling, but those are covered by the schema, and no output schema exists to explain.

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 four parameters (id, body, title, object enum) are already fully documented in the schema. The description only restates 'title + body', adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (add) and resource (note), enumerates the five parent record types it can attach to, and maps to a concrete endpoint (POST /<Object>/{id}/Notes). No sibling in the list adds notes, so it is trivially distinguishable from create_/update_/get_ tools.

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

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

Usage is implied by 'add a note to a Contact, Organisation, ...' but there is no explicit when-to-use framing, no prerequisites, and no named alternative. For a niche write tool with no close siblings, implied context is adequate but not rich.

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 with no readOnlyHint, so the description carries most of the behavioral burden. It discloses the backend endpoint but nothing about authentication, deduplication behavior, side effects (owner assignment, custom field creation), or what is returned after creation. A mutation tool with 18 parameters deserves more than a one-line API mapping.

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

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

Two very short sentences, front-loaded with the verb and the single required field. Nothing is wasted, though the terseness borders on under-specification rather than true conciseness.

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 create tool with no output schema and only a destructiveHint annotation, the description is thin. The agent gets the action and the required field but no information about deduplication, response payload, or which optional fields matter most.

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% and the description only restates that first_name is required, which the schema already marks as required with its own description. It adds no meaning for the remaining 17 parameters (owner_user_id, organisation_id, custom_fields semantics, etc.) and does not 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 specific verb and resource ('Create a contact') and even pins the underlying API call (POST /Contacts), so the agent knows exactly what the tool does. It stops short of any sibling differentiation, though the create/update verb pair makes the distinction mostly self-evident.

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

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

There is no when-to-use guidance at all: nothing about when to use this versus insightly_update_contact, whether duplicate contacts are rejected or merged, or what prerequisites (e.g. an existing organisation_id) apply. The parenthetical about first_name is a required-field note, not usage 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?

Beyond the destructiveHint=true annotation, the description discloses a genuinely behavioral fact: Insightly's server marks lead_status_id and lead_source_id required even though the local schema only lists last_name. That is non-obvious API semantics the schema does not carry. It still omits auth requirements and side-effect/error behavior.

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

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

Three tight sentences with no filler, front-loading the required field and then the hidden-required-field caveat. The trailing 'Insightly: POST /Leads.' is slightly redundant but harmless.

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 no output schema, the description covers the critical creation-time gotchas but says nothing about what the call returns (a created lead record/id), failure modes, or whether omitted optional fields are defaulted. Adequate, but leaves real gaps.

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

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

Schema coverage is low (38%) across 24 params, but the description compensates on the highest-risk gap by declaring last_name required and warning that lead_status_id / lead_source_id are required server-side, with pointers to the id-list tools. It does not add syntax or formatting detail for the remaining 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 (Create) plus resource (lead), and is unambiguous against the create_contact / create_opportunity / create_organisation siblings. An agent knows exactly which entity is being created without opening the schema.

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

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

The description routes the agent to prerequisite lookups (insightly_list_lead_statuses / insightly_list_lead_sources) for valid ids, which is concrete when-to-use guidance. It stops short of contrasting with insightly_update_lead or insightly_create_contact, so it lacks explicit exclusions.

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

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

Annotations already declare destructiveHint=true, so the safety signal is supplied structurally; the description adds nothing about side effects, required permissions, or whether the create is idempotent. A bare 'POST /Opportunities' restates structured information rather than adding behavioral context such as the impact of custom_fields or field validation behavior.

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

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

Two short sentences, front-loaded with the action and constraint. Nothing is padded, though the parenthetical requirement note duplicates the schema's 'required' declaration and thus earns 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 creation tool with no output schema and no annotations beyond a destructive hint, the description is too thin: it says nothing about the created record, which fields are commonly needed (e.g. organisation_id, owner_user_id), or the effect of omitting optional fields. The rich schema partly compensates, but the description itself leaves notable 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 85%, so the schema itself documents virtually every field including formats like the UTC date string and custom_fields semantics. The description only repeats that opportunity_name is required, adding no meaning 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?

'Create a sales opportunity' states a specific verb and resource, and the appended 'POST /Opportunities' pins the underlying operation. It is clearly distinct from siblings such as insightly_create_contact or insightly_create_lead by resource name, though it never explicitly contrasts itself with them or with insightly_update_opportunity.

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

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

The description gives no when-to-use context, no preconditions, and no pointer to the alternative (insightly_update_opportunity) when the record already exists. The only guidance is the redundant note 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 annotations only declare destructiveHint=true; the description adds nothing about write semantics beyond the word 'Create' - no permission requirements, no duplicate detection, no confirmation of what is persisted or returned. It does not contradict the annotation (creation is a mutation), but it carries almost none of the behavioral burden a mutating tool needs.

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

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

Two short sentences, front-loaded with the essential action; the trailing 'Insightly: POST /Organisations' adds a small amount of endpoint context without bloat. No wasted filler, but also very little substance per sentence.

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

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

For a 12-parameter mutation tool with no output schema and only a destructiveHint annotation, the description omits required-field emphasis, return behavior, and error/duplicate handling. It is not sufficient for an agent to invoke this confidently beyond the bare minimum.

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 description mentions no parameters at all, while schema description coverage is only 42% across 12 parameters. Fields such as custom_fields, owner_user_id and the address block are undocumented in the description, so it fails to compensate for the schema's gaps.

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 an organisation (company)') plus the underlying API endpoint, so the action is unambiguous. It does not, however, distinguish itself from the sibling insightly_update_organisation or explain how a created organisation relates to create_contact/create_lead workflows.

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 create versus update an organisation, no prerequisites (e.g. required fields, duplicate-name handling), and no mention of alternatives among the many sibling creation tools. The agent must infer all of this.

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 says 'Create a task', an additive operation. This contradicts the annotation, which claims potentially destructive behavior. Although the description adds useful default behavior for owner_user_id and completed, the contradiction requires score 1 per the rubric.

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

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

The description is three compact sentences with required-field information front-loaded. It includes key defaults and endpoint without any wasted words.

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

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

For a 14-parameter create tool with high schema coverage and no output schema, the description covers the required field and important defaults. However, it does not address the destructiveHint contradiction and does not describe any return value, leaving notable 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 93%, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining that owner_user_id is filled with the API key's own user via GET /Users/Me and that completed defaults to false.

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 'task', and notes title is required. This clearly distinguishes it from sibling tools such as insightly_update_task and insightly_create_contact.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. The description does not mention alternatives like update_task or explain when to create a task versus using another sibling tool.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds value beyond that by disclosing the returned payload fields and framing the call as a cheap credential/identity check, which is useful behavioral context. It does not cover error behavior if the key is invalid, 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 tight sentences, front-loaded with the core action and returns, followed by purpose and the underlying 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?

Although there is no output schema, the description enumerates the meaningful return fields, so an agent knows what it will get. For a zero-parameter read tool this is 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 zero parameters, the baseline is 4. The description correctly implies no inputs are needed and focuses instead on what the call returns.

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

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

The description states a specific verb and resource ('Fetch the user the API key belongs to') and enumerates the returned fields (USER_ID, name, email, admin flag). It is clearly distinguishable from the sibling insightly_list_users, which returns 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?

It gives clear context for when to use it: to confirm the key and pod are correct and to obtain your own id for owner fields. There is no explicit mention of the alternative (insightly_list_users) or a when-not condition, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. Beyond that, the description discloses that the response includes custom fields, tags and links, and maps the call to GET /<Object>/{id} — useful return-shape context that the annotation and schema do not provide.

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

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

Two sentences, zero waste, with the core action and scope front-loaded and the API mapping relegated to a trailing clause. Every element 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 partially compensates by noting the record's custom fields, tags and links. Combined with the readOnly annotation and fully documented params, an agent has enough to call it correctly, though richer return detail would help.

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 parameters are already documented in the schema, giving the baseline of 3. The description's enumeration of object types and 'by id' phrasing merely restates the enum and id parameter without adding format or constraint detail.

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

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

The description states a specific verb ('Fetch a single') and enumerates the exact resource types available, including the by-id scope. It implicitly separates itself from the plural sibling insightly_list_records via 'single ... by id', but never names that sibling explicitly.

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

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

Usage is implied by 'a single ... by id', which tells the agent this is the point-lookup path, but there is no explicit when-to-use guidance or statement of when to prefer list_records/search_by_tag instead. Adequate but not directive.

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 description's burden is lower. It adds the returned field shape and the underlying endpoint, but says nothing about result volume, paging behavior (despite a skip param), or instance-wide scoping.

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

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

Two short sentences with zero padding and the purpose front-loaded. The trailing endpoint note is mildly redundant but cheap and useful for API-literate agents.

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 trivial read-only list tool with no output schema, stating the returned fields plus the schema's paging params covers what an agent needs. Only the absence of any usage/routing context keeps it short 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?

Schema description coverage is 100% and both parameters (top, skip) are documented in the schema with ranges and defaults. The description adds no parameter guidance, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ("List the lead sources defined in the instance") and even enumerates the returned fields (LEAD_SOURCE_ID, name), which separates it cleanly from the sibling insightly_list_lead_statuses. An agent can identify what this returns without opening the schema.

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

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

There is no when-to-use guidance and no alternative named. A reasonable agent will infer it's for retrieving lead-source IDs to feed into create/update calls, but the description never states that use case or when it should be preferred over insightly_list_lead_statuses or 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?

readOnlyHint=true already tells the agent this is a safe, non-destructive read, so the bar is lowered. The description usefully adds that the payload contains LEAD_STATUS_ID, name, and type, and cites the underlying endpoint, but says nothing about pagination behavior or result ordering, which matters for a paginated list.

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 primary action and resource. The endpoint citation ('Insightly: GET /LeadStatuses') is slightly redundant but compact and harmless.

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 reference-list tool with full schema coverage and a readOnlyHint, the description covers purpose and returned fields adequately. Nothing critical is missing, though a note on paging or the default 100-record cap would round it out.

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

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

Schema description coverage is 100%, so top, skip, and include_converted are fully documented in the schema and the description need not repeat them. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the lead statuses defined in the instance') and even names the returned fields, so the agent knows it retrieves reference data rather than leads. It does not explicitly distinguish itself from lookalike siblings such as insightly_list_lead_sources or insightly_list_pipelines, but the resource noun is distinct enough to route correctly.

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

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

There is no guidance on when to call this versus the other list/reference tools, no mention of prerequisites, and no stated exclusions. The usage (fetching status definitions to map IDs to names) is only implicit in the field list, not spelled out.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the underlying GET /Pipelines endpoint and the shape of what comes back, but says nothing about pagination limits or ordering beyond what the schema's top/skip fields imply.

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

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

Two short sentences, front-loaded with the resource and the return fields. Nothing is wasted; the endpoint reference is a compact addition for integrators.

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

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

With no output schema, the description compensates by naming the fields returned, which is the essential information for a lookup tool. It is complete enough to call correctly, though paging behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so both parameters (top, skip) are fully self-documented with ranges and defaults. The description adds no paging guidance beyond that, 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 and resource ("List the sales and project pipelines") and enumerates the returned fields (PIPELINE_ID, name, opportunity vs project). It is naturally distinct from the sibling insightly_list_pipeline_stages, though it never explicitly routes the agent between the two.

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: as a read-only list of reference data, it is obviously the lookup call an agent would make before creating an opportunity. There is no explicit when-to-use, when-not, or mention of the adjacent insightly_list_pipeline_stages / insightly_list_lead_sources tools.

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds the underlying endpoint and the shape of returned records, which is useful, but it never addresses that results are capped (top max 500, API default 100) despite saying "every" stage — a mild behavioral gap rather than a contradiction.

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

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

One sentence, front-loaded with the action and resource, with the mapping use case and endpoint appended compactly. No sentence is wasted.

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

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

With no output schema, the description usefully compensates by listing the fields returned. The only unaddressed point is pagination vs the "every" claim, which the schema partially covers via top/skip but the description never reconciles.

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 only two paging parameters, and both are fully documented in the schema (top 1-500 with default, skip for paging). 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?

States a specific verb and resource ("List every pipeline stage") and enumerates the returned fields (STAGE_ID, PIPELINE_ID, name, order), so the agent knows exactly what comes back. It does not explicitly contrast itself with the sibling insightly_list_pipelines, but the resource nouns are distinct enough to disambiguate in practice.

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?

"Map an opportunity's or project's STAGE_ID to a stage name" gives a concrete when-to-use scenario tied to other tools' outputs. There is no explicit exclusion or named alternative, so it falls just short of the top band.

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=true annotation already declares the safety profile, so the description's added value is limited. It does disclose the underlying API path (GET /<Object>/{id}/Notes | Tasks | Events), but says nothing about default page size, paging behavior, or response shape beyond what the schema 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?

One tight sentence plus a short endpoint reference, with the core verb and scope front-loaded and 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?

No output schema exists and the description does not describe the returned payload, but the schema fully documents all 8 parameters and the read-only annotation covers safety, so an agent has nearly everything needed to call 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 description coverage is 100%, so all eight parameters (including top, skip, count_total, brief, updated_after_utc) are already documented in the schema. The description adds no format or defaulting detail beyond that baseline.

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

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

States a specific verb (List), resource (Notes, Tasks, Events) and scope (attached to one record of five types), and frames it as the record's activity history, which cleanly distinguishes it from siblings like get_record or list_records.

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 'activity history of that record' phrasing implies when this tool is useful, but there is no explicit when-to-use versus alternatives (e.g. get_record, list_records, search_by_tag) and no stated 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?

With readOnlyHint already declaring the safety profile, the description adds real behavior: the dual endpoint routing (Search vs plain GET), the constraint that field_name and field_value must be supplied together, and the UPPER_SNAKE field-naming convention including custom fields like Industry__c. It stops short of describing pagination semantics or result shape beyond the count_total mention.

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 paragraph that front-loads the core action before the routing detail; nearly every clause carries information. It is slightly packed with the endpoint paths, but no sentence is wasted.

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

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

For an 8-parameter listing tool with no output schema and a fully documented input schema, the description supplies the endpoint routing, filter pairing rule, and field naming plus the count_total response note. The main gap is that return shape and pagination behavior (top/skip interaction) 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: the pairing requirement for field_name/field_value, the accepted field-name format, and the custom-field example Industry__c. That goes beyond the schema's terse per-parameter text.

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

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

The description gives a specific verb (list/search) and resource (records of one of eight named types), and enumerates the exact object enum values, so the agent knows precisely what it operates on. It does not, however, differentiate itself from siblings like insightly_get_record or insightly_search_by_tag, which also retrieve records, leaving that routing to inference.

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

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

It clearly states the conditions that switch the tool between search and plain listing: field_name + field_value (both required together) or updated_after_utc selects GET /<Object>/Search, otherwise GET /<Object>. This is strong conditional guidance, but it never says when to prefer this tool over insightly_search_by_tag or insightly_get_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?

readOnlyHint=true already tells the agent this is a safe read. The description only adds the backing endpoint (GET /Users) and the resolution use-case; it says nothing about ordering, paging behavior, rate limits, or what a user record contains.

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

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

Two short sentences, zero filler, with the operation and its purpose front-loaded. Nothing could be removed without losing routing value.

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

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

For a zero-required-param, read-only list tool with fully documented parameters and no output schema, the description covers what an agent needs. It could note that the result feeds OWNER_USER_ID fields into other tools' arguments, but that is a minor omission.

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

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

Schema description coverage is 100%, so top/skip/count_total are fully documented in the schema and the description adds nothing beyond them. Baseline 3 is appropriate when the schema carries all parameter semantics.

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

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

States a clear verb+resource ('List the users in the Insightly instance') and adds the concrete reason it exists (resolving OWNER_USER_ID / RESPONSIBLE_USER_ID). It implicitly distinguishes itself from the sibling get_current_user by covering the whole instance, though it never names that sibling.

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

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

Gives a clear trigger: call this when you need to resolve OWNER_USER_ID / RESPONSIBLE_USER_ID. It stops short of an explicit exclusion (e.g. 'use insightly_get_current_user for just the authenticated user'), so it is context without alternatives.

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 underlying API route (GET /<Object>/SearchByTag?tagName=), which is mildly informative but does not disclose pagination behavior, result ordering, or what the response looks like. Minimal added value beyond annotations.

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

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

Two short sentences, front-loaded with the resource and filter. The second sentence is a raw API path that borders on redundant documentation, but the total size is tight and easy to scan.

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

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

No output schema exists, and the description never states what is returned (a list of matching records, or {total_count, items} when count_total is set). For a read-only search tool with well-documented parameters it is adequate, but the return shape and paging expectations are left to the caller's inference.

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

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

Schema description coverage is 100%, so every parameter (tag, top, skip, brief, object, count_total) is already documented in the schema. The description only echoes the tag filter and the object enum values, adding no syntax or format detail beyond 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 (List) and enumerates the exact record types it operates on (Contacts, Organisations, Leads, Opportunities, Projects), plus the filtering dimension (tag). It does not explicitly differentiate itself from sibling insightly_list_records, so an agent must infer the distinction from the tag filter 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?

The 'carrying a tag' phrasing implies the tool is for tag-based lookups, but there is no explicit when-to-use guidance, no statement of when to prefer this over insightly_list_records or insightly_get_record, and no prerequisites or exclusions.

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

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

Annotations declare destructiveHint=true, and the description usefully clarifies that only passed fields change (v3.1 partial update) and names the underlying PUT /Contacts call. This adds real context against the scary destructiveHint, but there is no mention of permissions/auth, what happens to omitted fields' behavior at scale, or error handling.

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

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

Three short sentences with the core operation front-loaded and zero filler. Reasonably tight for the complexity involved, though the API-path sentence is only marginally useful to an agent.

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

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

For a 19-parameter destructive mutation with no output schema, the description covers the important partial-update behavior but omits permission requirements, required-field emphasis, and any failure/return context. 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 most fields are self-documented and the baseline is 3. The description adds no per-parameter meaning beyond the general 'only passed fields change' rule, and never calls out the required contact_id or the custom_fields clearing semantics that the schema handles.

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 ('Update a contact'), and the resource name distinguishes it from the sibling update tools (update_lead, update_opportunity, update_organisation, update_task). It does not explicitly contrast with create_contact, but the verb makes the distinction obvious.

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

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

No guidance on when to use this versus alternatives (e.g., create_contact) or on prerequisites such as needing an existing contact_id. The 'partial update' note describes behavior, not usage context, so the agent gets no routing 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 only flag destructiveHint=true, so the description correctly adds the non-obvious partial-update semantics and names the underlying endpoint (PUT /Leads with LEAD_ID), which helps interpret errors. It does not disclose the consequences of the destructive hint — e.g. that omitted fields survive but null clears values, or that this overwrites existing lead data — and it does not contradict 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?

Three short sentences with the purpose front-loaded and no filler. The endpoint sentence is the only one of debatable value, but it is compact and could aid error interpretation.

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

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

A 25-parameter mutation tool with 40% schema coverage, no output schema, and minimal annotations needs considerably more description than three sentences. The agent gets no guidance on id sourcing, partial-update edge cases, or return behavior.

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

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

Schema description coverage is only 40% across 25 parameters, so the description is expected to compensate and does not: it names only the implicit LEAD_ID identifier. Nothing is said about the relation id fields, custom_fields shape, or the meaning of ids such as lead_status_id 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 and resource ('Update a lead'), which cleanly separates it from insightly_create_lead and insightly_update_contact. It does not, however, contrast itself with siblings like insightly_get_record to confirm an existing lead is being modified.

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 a useful partial-update note that tells the agent it may send a sparse payload. Beyond that there is no when-to-use guidance: no mention of reading the lead first, of prerequisite ids, or of which sibling to use instead for creation or lookup.

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, so the safety profile is already flagged; the description adds genuine mitigating context by disclosing that unspecified fields are preserved (partial update), which softens the destructive reading. It still omits auth requirements, failure behavior for unknown ids, and whether changes are reversible.

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 redundancy; the mutating-field list comes first and the patch caveat second. The trailing REST endpoint note ("PUT /Opportunities with OPPORTUNITY_ID") is borderline filler but does anchor the operation.

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 the essential shape but leaves gaps: no return-value expectation, no error/id-not-found behavior, and no guidance on the two owner-ish id fields. Adequate but not 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 86%, so the baseline is 3 and the schema carries most parameter meaning. The description's field list loosely maps to bid_amount/probability/forecast_close_date/owner/details, but "owner" is ambiguous between owner_user_id and responsible_user_id, both of which lack schema descriptions.

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 (an opportunity), and enumerates the field categories affected (value, probability, dates, owner, details). This clearly separates it from insightly_create_opportunity by name, though the description itself never explicitly routes the agent away from siblings.

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

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

"Only the fields you pass are changed" gives useful patch semantics for how to call it, but there is no explicit when-to-use guidance versus insightly_create_opportunity, no prerequisites, and no mention of required permissions or what happens on an invalid 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 supply destructiveHint=true, and the description adds a valuable nuance: that a PUT call still behaves as a partial update ('only the fields you pass are changed'), countering the usual full-replacement assumption. It stops short of disclosing permission requirements, reversibility, or what a failed/partial update returns, so it adds some value but not rich behavioral context.

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

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

Three short, front-loaded sentences with zero filler; the purpose leads and the partial-update caveat follows. Efficient, though it spends a clause on the raw REST verb/path, which is operationally marginal for an agent.

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

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

For a 13-parameter mutation with no output schema, the description covers purpose and partial-update semantics but leaves many parameters and any permission/return behavior unaddressed. Adequate but with clear gaps given the tool's complexity.

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

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

Schema coverage is only 46%, leaving phone, website, and all five address_billing_* fields undocumented in the schema. The description adds no parameter-level meaning beyond the generic partial-update statement, so it does not compensate for the coverage gap across 13 parameters.

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

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

States a clear verb+resource: 'Update an organisation', and the sibling set (update_contact, update_lead, etc.) makes the target resource unambiguous. It doesn't explicitly differentiate from those siblings, but the resource name is specific enough for selection.

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' implies partial-update usage, which is genuinely useful for a PUT-style endpoint. However, there is no when-to-use vs when-not guidance, no prerequisite or permission notes, and no alternative tool mentioned.

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

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

Annotations only declare destructiveHint=true, so the description usefully adds the partial-merge behavior (unspecified fields are preserved). However, it says nothing about authentication/permission requirements, whether overwriting custom_fields or statuses is reversible, or what happens to fields set to null — meaningful gaps for a mutation tool flagged destructive.

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

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

It is short and front-loads the action plus the mutable-field list, but the trailing "Insightly: PUT /Tasks with TASK_ID." is implementation detail of limited value to an agent selecting the tool, and the field enumeration partially duplicates the schema.

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

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

For a 15-parameter mutation with no output schema, the description omits the return shape (does it echo the updated task?), error behavior on invalid ids, and any destructive-change caveat despite the destructiveHint annotation. The partial-update statement is the one strong piece of context, leaving the definition minimally adequate rather than 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 93%, so the schema already documents nearly every parameter including formats (e.g. "yyyy-MM-dd HH:mm:ss" UTC) and status value guidance. The description only names a subset of fields in prose and adds no syntax, defaults, or id-resolution 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?

The description gives a concrete verb+resource ("Update a task") and enumerates the mutable fields (completed, due date, status, assignee, details), so the agent knows exactly what this tool changes. It doesn't explicitly differentiate itself from insightly_create_task or the other insightly_update_* siblings, but update-vs-create is self-evident from the name.

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

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

It states the key edit semantics — "Only the fields you pass are changed" — which is genuinely useful for a partial-update tool, but there is no explicit when-to-use guidance, no prerequisites (e.g. needing a valid task_id or fetched record), and no mention of when another sibling (create_task, get_record) would be preferred.

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