Freshsales MCP by usefulapi

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

Annotations already flag readOnlyHint=false and idempotentHint=false; the description reinforces write semantics ('WRITE:') and adds the genuinely useful risk that the call may duplicate an existing company. It does not say what comes back after creation (no output schema exists), which is the main remaining gap.

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

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

Three short sentences, front-loaded with the WRITE marker and the core action, then the requirement, then the duplicate warning. Zero filler; every sentence carries information.

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

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

For a 14-parameter mutation with a nested object and no output schema, the description covers the call decision but says nothing about the creation result (returned id/record shape) or how created custom fields behave. Adequate given the rich schema, but thin for a creation 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%, so every parameter (including the nested custom_field object and the size-bucket codes) is already documented in the schema. The description only restates that 'name' is required, adding no semantic meaning beyond structured data — baseline 3.

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

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

States a specific verb and resource ('create an account') and disambiguates the entity type with '(company)', which separates it from sibling create tools for contacts, deals, tasks, notes and appointments. 'name is required' adds the mandatory field constraint up front.

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

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

Explicitly tells the agent to run freshsales_search first because the call may create a duplicate company, naming the concrete alternative tool. It lacks exclusions (when not to create) and any permission or prerequisite notes, 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?

Annotations already declare readOnly=false, destructive=false, openWorld=true, idempotent=false, so the safety profile is covered. The description adds value beyond them by disclosing that attendees may be notified by Freshsales (a side effect not captured anywhere else) and by naming the underlying POST endpoint. It stops short of saying whether notification can be suppressed or what is returned.

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

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

A single dense sentence front-loads the operation, its required temporal fields, and its optional attachments, followed by a short endpoint note. Nothing is padded or repeated.

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

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

With 10 parameters fully described in the schema and no output schema, the description only needs to frame intent and side effects, which it largely does. The gap is the attendee notification behavior: it says notification may happen but not whether the caller controls it, which matters for a scheduling write.

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

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

Schema description coverage is 100%, so every parameter including target_type's enum and the ISO 8601 date formats is documented in the schema itself. The description only restates the headline structure (start/end, optional contact/account/deal attachment, attendees) without adding format or constraint detail. Baseline 3 applies.

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

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

The description names a specific verb and resource (create an appointment/meeting) and enumerates its shape: start, end, optional attachment, attendees. The 'WRITE:' prefix also signals its class of operation. It does not explicitly contrast with the other create_* siblings, but the resource distinction 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 implied — create this when you need to schedule a meeting on the calendar with a time range. There is no explicit statement of when to prefer it over freshsales_create_task or freshsales_create_note (e.g. meetings vs. to-dos), and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the description doesn't need to restate that this is a non-idempotent write. It adds real value beyond the structured data by warning that the call may silently create a duplicate of an existing contact. It stops short of saying what the response contains or how to undo a bad 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?

Three short sentences, front-loaded with the write marker and followed immediately by the constraint and the duplicate risk. Every clause carries distinct information, and the endpoint is tucked away at the end where it costs 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 17-parameter, zero-required create tool with no output schema, the description supplies the two things the schema cannot: the hidden required-field constraint and the duplicate risk with a mitigation path. The only gap is the absence of any return-value or failure-mode information, which would help an agent that must confirm creation succeeded.

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

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

With 100% schema description coverage the baseline is 3, but the description adds a cross-field constraint the schema does not encode: the schema marks zero required parameters, yet the description reveals that email or mobile_number is effectively mandatory. It doesn't cover the many other fields, which the schema already documents.

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

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

The description opens with a specific verb and resource ("WRITE: create a contact") and names the API endpoint, so the agent knows exactly what it does. Differentiation from the create_* siblings is only implicit via the resource noun in the name, with no explicit contrast drawn.

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 a hard prerequisite ("Freshsales requires an email or a mobile number") and explicitly routes the agent to an alternative first step: "search first (freshsales_lookup by email)". Both the when-to-use condition and the named alternative tool are given, leaving nothing 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the description doesn't need to restate those. It usefully adds that stage and pipeline default to the first of the default pipeline and that it performs a POST to /deals, which is meaningful context beyond the annotations. It doesn't cover auth requirements, rate limits, or side effects beyond creation, so it falls just 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 short sentences, front-loaded with the action verb and mutation signal, then required fields and defaults, then the endpoint. Every sentence carries information and nothing is wasted.

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

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

For a mutation tool with annotations covering the safety profile and a schema with full parameter descriptions, the description provides the essential missing context: required fields, default behavior, and the underlying HTTP method. Without an output schema, the lack of return-value documentation is a minor gap but not critical.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter detail. The description adds value by explicitly naming the three required fields and clarifying that contact_ids attach existing contacts (rather than creating new ones) and that stage/pipeline have fallback defaults.

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

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

The description opens with 'WRITE: create a deal,' pairing a specific verb with the exact resource. The 'WRITE:' prefix also signals the mutation nature immediately, and the resource distinguishes it from sibling create tools like freshsales_create_account and freshsales_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?

It states the required fields and default behavior for stage and pipeline, but gives no guidance on when to use this versus alternatives like freshsales_update_deal or freshsales_create_contact. There is no context about prerequisites such as required permissions or when a deal should not be created.

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=false, idempotentHint=false and destructiveHint=false, so the write/safety profile is covered. The description adds genuinely new context — the note is visible to the team on the record and hits POST /notes — but says nothing about whether notes can be edited later or what a repeat call does, and the 'WRITE:' prefix merely restates 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, front-loaded with the write intent and the target resource; every clause carries information and there is no 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?

All three required parameters are covered by the schema, the target object types are enumerated, and no output schema exists so return values need no explanation. It stops short of telling the agent where to get a valid target_id or what to expect on success.

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 are documented with an enum for target_type, so the baseline is 3. The description's 'contact, account or deal' loosely mirrors the enum but adds no format, length, or ID-resolution detail beyond the schema.

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

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

States a specific verb and resource — 'add a note to a contact, account or deal' — so the agent knows exactly what is created and where it attaches. It is clearly distinct from the create_account/contact/deal siblings, though it never names update_note or explains the split from it.

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

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

There is no explicit guidance on when to use this versus alternatives such as freshsales_update_note or freshsales_create_task. Usage is only inferable from the phrase 'add a note ... on the record'; no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the write semantics are known. The description reinforces this with 'WRITE:' and the POST /tasks endpoint, which is consistent, but adds nothing about side effects such as whether duplicate tasks are created on retry or what gets returned.

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. The verb/scope comes first, followed immediately by the required-field constraint and endpoint. Every clause earns its place.

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

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

For a 6-parameter mutation with no output schema, the description covers purpose, required inputs and the attachment model. It could still mention the return value (e.g. the new task id) since no output schema exists, which keeps it from a 5.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema itself, including the target_type enum and the cross-reference to freshsales_list_owners. The description only restates which fields are required, which is already encoded in the required array; 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 ('create'), a specific resource ('a task (to-do)'), and the scope of attachment (contact, account or deal). The resource name alone cleanly separates it from sibling creators like freshsales_create_note or freshsales_create_appointment.

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

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

The 'WRITE:' prefix and required-field list imply this is the tool for creating tasks, but the description never says when to prefer it over update_task or create_note, nor any prerequisites (permissions, dedupe on existing tasks). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint and the embedding behavior, but says nothing about behavior on a missing/invalid id or the shape of the returned payload.

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

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

A single tightly packed sentence front-loads the resource and scope, followed by the endpoint as a compact reference. No filler sentences.

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

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

For a two-parameter read tool with full schema coverage and no output schema, the description conveys the return unit (an account with its fields, plus optional embeds), which is enough to call it correctly. Only error/missing-record behavior is left unaddressed.

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 account_id and the include enum are already fully documented. The description names a few example embed types (contacts, deals, tasks, appointments, owner) but adds no syntax, limits, or semantics beyond the schema's own 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 (get) and resource (one account/company) scoped by id, and clarifies that related records are optional embeds rather than separate calls. This clearly separates it from freshsales_list_accounts, freshsales_search, and freshsales_lookup.

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

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

The phrase 'optionally with related records embedded' implies when to use the include parameter, but the description never names an alternative tool or states exclusions (e.g., use search when you lack an id). Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the concrete endpoint GET /appointments/{id} and, more usefully, that attendees are included in the result — a return-shape detail not available elsewhere since there is no output schema. It says nothing about behavior for a nonexistent or inaccessible id.

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

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

Two terse sentences, front-loaded with the outcome, then the endpoint. Nothing is padded and nothing repeats the title verbatim.

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

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

For a one-parameter read-only tool with no output schema and full annotation coverage, the essentials are present: what comes back (appointment plus attendees) and which route it hits. Only the failure case for an invalid id is missing.

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

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

Schema description coverage is 100% and there is a single documented parameter (appointment_id, positive integer), so the schema carries the load. 'by id' adds no syntax, format, or sourcing hint (e.g., where to obtain the id) beyond what the schema 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?

The description names a single specific resource and scope: 'One appointment by id with its attendees,' which implicitly separates it from the sibling freshsales_list_appointments and freshsales_create_appointment. It never names those siblings explicitly, so the differentiation is inferential rather than stated.

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

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

'by id' implies you need a known appointment id, which implies the alternative (list/search/lookup) when you don't have one, but the description never says that. No exclusions or alternative routing are given despite freshsales_list_appointments, freshsales_search and freshsales_lookup all being plausible overlaps.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that — that the response contains all fields and that include embeds related records — but says nothing about what happens if the id doesn't exist, permission scoping, or the payload-size cost of requesting many includes.

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: the core behavior and the optional include capability are front-loaded, and the endpoint reference is a compact anchor. Nothing is padded or repeated.

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

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

With no output schema, the description carries the burden of describing the return and does so ('all its fields' plus optional embedded relations). For a 2-parameter read tool with full schema coverage this is essentially sufficient, though a note on missing-id behavior or include payload cost would close the last gap.

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

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

Schema description coverage is 100%, so both contact_id and include are already documented, making the 3 baseline. The description's list of embeddable relations (notes, tasks, appointments, deals, sales_accounts, owner, sales_activities) largely restates the enum and the schema's own 'Related records to embed' text, adding little beyond naming examples.

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

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

States a specific verb and resource — 'One contact by id with all its fields' — and names the underlying endpoint GET /contacts/{id}, so it's immediately distinguishable from get_account, get_deal, or list_contacts. It does not explicitly contrast itself with search/lookup, which keeps it just 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: you must already have a contact_id, and include is described as optional. The description never says when to prefer this over freshsales_search or freshsales_lookup, nor when to add include versus making a separate related-record call. The enumeration of include targets gives some hint about intent but no explicit conditionals.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered; the description adds the substantive behavioral fact that related records are opt-in embeds via an include list, and names the underlying endpoint GET /deals/{id}. It omits error behavior (e.g. unknown id) and whether embeds cost extra calls, which keeps it below a 5.

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

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

One dense sentence with the resource and return fields front-loaded, then the endpoint. The parenthetical embed list is long but earns its place; the trailing 'GET /deals/{id}' is mildly redundant with 'by id' but useful for mapping to the REST API.

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 carries the burden of describing return content and does so (core deal fields plus optional embedded related records). Missing only edge-case behavior on invalid ids or partial permissions for a complex CRM resource.

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 beyond 'Related records to embed' by naming concrete embed targets (contacts, sales_account, deal_stage, owner, notes via sales_activities) and making clear the embeds are optional. It does not explain deal_id validation (positive integer) beyond the schema.

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

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

States a specific verb and resource ('One deal by id') and enumerates the returned fields (amount, expected close, probability, stage/pipeline/owner ids), so an agent can distinguish it from freshsales_list_deals or freshsales_get_account 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 only implied by 'by id' — the description never says when to prefer this over list_deals, search/lookup, or when to add embeds versus making a follow-up call for contacts or notes. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the raw endpoint path, with no note about error behavior for missing ids, permissions, or whether related records are included.

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

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

Two terse fragments, front-loaded with the essential fact and the endpoint. Nothing extraneous, though the telegraphic style leaves no room for any clarifying detail.

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?

Single-param read tool with annotations covering safety, but there is no output schema and the description says nothing about what a task object contains or what happens when the id does not exist. For a fetch-by-id tool that gap matters to an agent planning the call.

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

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

Schema description coverage is 100% and task_id is fully documented as an integer id, so the baseline is 3. The description's 'by id' restates the schema without adding format, sourcing, or validation 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?

'One task by id' plus the GET endpoint states a specific verb and resource, so the retrieval intent is clear. However, it does not distinguish itself from freshsales_list_tasks or freshsales_get_appointment/deal siblings; the agent must infer that 'by id' means a single record versus the list variant.

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

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

No guidance on when to call this versus freshsales_list_tasks or when a task id is already known. The agent must infer that this requires a previously obtained task_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?

With readOnlyHint and destructiveHint already declared, the description adds real value: a fixed page size of 25, the concrete attributes returned (name, location, open deals amount, last contacted), and the underlying endpoint. It stops short of stating whether the total record count or pagination metadata comes back, so the agent cannot fully plan multi-page iteration.

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

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

A single front-loaded sentence carrying the resource, the required scope, the page size, and the returned fields, followed by the endpoint. Nothing is redundant and nothing an agent needs first is buried.

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

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

No output schema exists, so the description's enumeration of returned fields is necessary and well done, and pagination mechanics are at least sketched. The remaining gap is total-count or next-page signaling for a paged list tool, which the agent would need to page reliably.

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 every parameter is already documented in the schema, which sets the baseline at 3. The description reinforces view_id's provenance from freshsales_list_account_views and implies the sortable fields by naming open deals amount and last contacted, but adds no syntax or default behavior beyond what the schema 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 ('List the accounts (companies)') and adds the scoping mechanism (a view identified by view_id), plus the fields returned. It also implicitly separates itself from freshsales_list_account_views by pointing to it as the source of view_id, though it never contrasts itself with freshsales_search or freshsales_lookup for ad-hoc retrieval.

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

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

The parenthetical 'view_id from freshsales_list_account_views' tells the agent the prerequisite for calling this tool, which is genuine usage context. However, there is no guidance on when to prefer this over the sibling search/lookup tools, and no mention of what happens when a view has more than the first page of results.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the REST endpoint and the cross-tool dependency on a view id, though it says nothing about the shape or size of the returned view 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 sentences, zero filler: the resource definition and example come first, then the actionable dependency and endpoint. Every clause earns its place.

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

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

For a zero-parameter, annotation-covered, read-only listing tool this is essentially complete: it says what is listed, gives an example, and explains why the result matters. Only a hint about the return structure (e.g., that each entry carries an id and name) is missing, which is minor given no output schema exists.

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

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

The tool takes zero parameters, so the schema carries no semantics to supplement. The description correctly signals a no-argument listing call and focuses on the returned concept (saved view ids) instead, which is the right emphasis.

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 a precisely scoped resource ('saved account (company) views'), reinforced by a concrete example ('My Accounts') and the underlying endpoint GET /sales_accounts/filters. An agent can easily distinguish this from freshsales_list_accounts or freshsales_list_contact_views/deal_views.

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 names the downstream consumer: 'A view id is needed by freshsales_list_accounts', which tells the agent this is a prerequisite/discovery call. It gives clear context but stops short of stating exclusions or the full workflow ordering (e.g., call this only if you intend to filter by view).

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add operational context — which it does, disclosing the underlying endpoint (GET /appointments) and the record fields returned. It does not mention ordering, totals, or behavior at the last page, leaving a small gap.

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

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

A single front-loaded sentence carries the filter semantics and returned fields, with the endpoint appended as a compact implementation hint. No redundancy with the title or schema.

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

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

With no output schema, the description usefully enumerates the returned fields and states the filter scope, which is enough to call the tool correctly. It stops short of describing result volume, ordering, or the total-count/next-page signal an agent might need to paginate.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by glossing 'open' as 'upcoming' and enforcing the 'one filter per call' constraint, which the enum alone does not convey. Page-size behavior is left entirely to the schema, which is acceptable given full coverage.

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

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

States a specific verb and resource ('List appointments') plus the scope of what can be listed (open vs. complete) and the fields returned ('title, time, location and creator'). An agent can distinguish this from freshsales_get_appointment (single record) and freshsales_create_appointment without opening any schema.

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

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

Clarifies that open means upcoming and complete means past, so the agent knows which filter value matches intent, and the 'one filter per call' note signals that both statuses require two calls. It stops short of naming an alternative (e.g., the generic freshsales_search) for filtering by title, creator, or date.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: fixed page size of 25, the next_page continuation mechanism, and the fact that results are view-scoped rather than account-wide. It does not mention auth requirements or rate limits.

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

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

One dense, front-loaded paragraph that opens with the core verb+resource and ends with the endpoint. Every clause carries information, though the returned-field list and parentheticals make it slightly run-on compared to a tighter phrasing.

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 listing the fields returned and describing pagination, which is the key missing structured information. Only minor gaps remain, such as whether total page counts or cursors are returned alongside the records.

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 baseline would be 3, but the description contributes real meaning: it explains where view_id comes from, that pagination is 25-per-page, and that next_page should be followed. Sort and sort_type are left entirely to the schema, but their semantics are self-evident from the enums.

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 contacts) scoped to a view, and explicitly distinguishes itself from the sibling freshsales_list_contact_views by naming it as the source of view_id. It also enumerates returned fields and the underlying endpoint, so an agent can identify exactly what this does versus freshsales_get_contact or freshsales_search.

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 prerequisite ('get view_id from freshsales_list_contact_views') and pagination follow-up ('use next_page'), which tells the agent how to chain calls. It stops short of stating when to prefer this over search/lookup for contact retrieval, so there is no explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context beyond annotations: it discloses the endpoint, gives examples of saved views, and warns that view ids vary by account.

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 short sentences, front-loads the core action, includes examples, and ends with the endpoint. Every sentence adds useful information without repetition.

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

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

With no output schema, the description sufficiently explains that the tool returns saved contact views and why the result matters. It could describe the exact return fields (e.g., id and name), but for a zero-parameter list tool this 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics and appropriately focuses on the tool's output and purpose.

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

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

The description uses a specific verb and resource: 'List the saved contact views (filters) of the account.' It provides concrete examples ('My Contacts', 'New Contacts', 'All Contacts') and distinguishes the tool from freshsales_list_contacts by explaining that its output supplies a needed view id.

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 clearly states the practical purpose: obtaining a view id required by freshsales_list_contacts, and notes that ids differ per account. It does not explicitly name when not to use this tool or mention alternative view-list tools, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the endpoint path and the shape of the returned records, which is modest extra context for a zero-argument read tool.

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

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

A single short sentence that front-loads the action and resource with zero padding. Nothing is wasted, and the scale of the description matches the simplicity of the tool.

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

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

For a parameterless, read-only selector with no output schema, the description does enough: it names the fields returned. The only missing element is a hint about what an agent would do with these ids, which would make the tool easier to place in a workflow.

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 and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; the parenthetical listing returned fields is a small bonus.

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 deal pipelines') and names the returned fields (id, name), so an agent knows exactly what comes back. It does not distinguish itself from the nearby freshsales_list_deal_stages sibling, which is the one plausible confusion point.

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 guidance, no mention of the typical purpose (resolving pipeline ids before creating or filtering deals), and no reference to alternatives such as freshsales_list_deal_stages or freshsales_list_options. Usage has to be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds genuinely new behavioral context: the fixed 25-per-page paging behavior, the subset of deal fields returned, and the underlying endpoint. It doesn't discuss rate limits or ordering defaults beyond what the schema already states.

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

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

A single dense sentence with the key scoping and paging facts front-loaded, followed by the endpoint. Efficient, though slightly crammed with parenthetical asides.

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 a fully documented 4-param schema and no output schema, the description covers scope, paging and returned fields. Only ambiguity about the response envelope or total counts remains, which is minor.

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

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

Schema description coverage is 100%, so the schema already documents page, sort, sort_type and view_id. The description adds minor value by restating the page size and the origin of view_id, but nothing beyond the schema baseline.

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

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

States a specific verb and resource ('List the deals in a view') plus the scope constraint (driven by view_id) and the returned fields, which cleanly separates it from get_deal and from view-listing siblings. An agent can pick it 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 parenthetical '(view_id from freshsales_list_deal_views)' gives the prerequisite and points to the sibling that produces the required id. It does not say when to prefer this over e.g. freshsales_search or freshsales_list_sales_activities, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral content beyond that: the default-pipeline behavior when pipeline_id is omitted and the exact shape of the returned records (id, name, deal_pipeline_id). No rate-limit or pagination notes, but for a selector endpoint that is minor.

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

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

A single dense sentence followed by a compact endpoint reference; the core scoping rule is front-loaded ahead of the detail. It is appropriately sized for a one-parameter selector tool, with no filler.

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

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

For a single optional parameter with full schema coverage and read-only annotations, the description supplies the missing pieces: what records look like (compensating for the absent output schema), the default behavior, and how the returned id is consumed. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100% and the schema already ties pipeline_id to freshsales_list_deal_pipelines and states the default-when-omitted rule. The description restates that default behavior and adds no new syntax, type, or constraint information, 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 and resource ('List deal stages'), enumerates the returned fields (id, name, deal_pipeline_id), and scopes it to the default pipeline or a named pipeline_id. This lets an agent tell it apart from freshsales_list_deal_pipelines without opening either schema.

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

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

Gives clear context: call it with pipeline_id to get a specific pipeline's stages, omit it for the default pipeline. It also adds downstream guidance ('Use the id as deal_stage_id'), which is a strong chaining hint, but it never explicitly says to call freshsales_list_deal_pipelines first to obtain a pipeline_id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the underlying endpoint (GET /deals/filters) and the fact that the output contains view ids, which is useful context, but says nothing about pagination, result volume, or response shape.

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

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

Two tight sentences: what it lists, an example value, and the dependency that motivates calling it. The downstream dependency is front-loaded and no sentence is 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 zero-parameter, read-only listing tool with no output schema, the description covers purpose, a sample value, and how the result is consumed. The only minor gap is that it doesn't state the shape of the returned view objects (ids plus names), which is implied rather than described.

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 baseline this sits at 4; there is nothing for the description to disambiguate. Nothing in the description misleads about inputs.

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 saved deal views of the account') with a concrete example ('Open Deals'), so the agent knows exactly what comes back. It does not explicitly differentiate itself from adjacent siblings such as freshsales_list_deal_pipelines or freshsales_list_deal_stages, 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?

Gives explicit forward context: 'A view id is needed by freshsales_list_deals', telling the agent exactly when this tool is a prerequisite step. It offers no when-not or exclusion guidance against the other list_*_views siblings, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the return shape (id and name pairs) and that the underlying call is a GET against /selector/{kind}, which tells the agent the data is static configuration rather than tenant records.

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, purpose front-loaded, with the kind list embedded in the first sentence so the agent reads the essential contract immediately. The 14-value enumeration largely duplicates the schema enum, which is mild waste, though it lets the agent decide fit without opening 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 one-parameter read-only lookup with no output schema required, everything an agent needs is present: what it returns (id/name pairs), which kinds are valid, and how to consume the output in write tools. Nothing material is left unspecified.

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% with a single fully enumerated parameter, so the baseline would be 3. The description earns extra credit by explaining what the parameter semantically selects (a field's configured choice set) and how the returned ids feed the *_id fields of write tools, going beyond the terse schema line "Which list of choices."

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 configured choices (id and name) for a field") and enumerates exactly which field kinds are covered, which cleanly separates it from sibling list_* tools that return records rather than schema metadata. The trailing endpoint reference (GET /selector/{kind}) confirms the scope.

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 concrete forward guidance: "Use the ids in the *_id fields of the write tools," which tells the agent this is a prerequisite helper for create/update calls. It does not explicitly rule out alternatives (e.g., freshsales_lookup or freshsales_search) or state when not to call it, so it stops short of full 5-level routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile needs no restatement. The description adds useful context beyond that — the returned fields and the purpose of the returned id — plus the underlying endpoint, but says nothing about pagination, result limits, or permission requirements for an openWorld read.

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 and an endpoint reference, all of which earn their place. The core capability is front-loaded and the usage hint follows immediately 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 zero-parameter read tool with no output schema, the description covers what it returns (id and name) and how to consume it, which is sufficient to call it correctly. It omits whether the list is paginated or filtered by visibility, a minor gap for a selector endpoint.

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 the baseline is 4 and there is nothing for the description to compensate for. It does add meaning by explaining the semantics of the returned id (owner_id for create/update calls), which is more than the empty schema conveys.

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 of the account' — and clarifies the payload ('id and name'), which no sibling does. No sibling is named as a contrast, but there is no other user-listing tool in the set to confuse it with, so the resource itself does the differentiation.

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

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

Gives a concrete downstream use case: 'Use the id as owner_id when creating or updating records,' which tells the agent exactly when to reach for this tool. It stops short of naming alternatives (e.g., lookup or search) or stating exclusions, so it is clear context rather than a full when/when-not routing rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds the endpoint and types of records, but says nothing about result volume, scoping, or pagination behavior beyond what annotations/schema give.

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 resource and activity examples front-loaded. The trailing 'GET /sales_activities' is mildly redundant with the tool name but cheap.

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

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

For a simple read-only list tool whose annotations and schema are complete, the description is minimally adequate. It does not clarify whether results are scoped to a specific account/owner or how paging metadata is returned, which is the one real ambiguity an agent would hit.

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% with both page and per_page fully described (25 per page, 1-100 range), so the schema does the heavy lifting. The description contributes nothing about pagination, which is acceptable at baseline but not additive.

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

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

Specific verb + resource ('List logged sales activities') with illustrative activity types (calls, meetings, emails) and the underlying endpoint, so the agent knows exactly what it returns. The phrase 'of the account' is slightly confusing since there is no account parameter, which keeps it from a 5.

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

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

No guidance on when to pick this over siblings like freshsales_list_appointments, freshsales_list_tasks, or freshsales_search. The name implies a listing operation, but there are no exclusions, prerequisites, or alternative-routing 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 already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond them by disclosing the return shape (title, due date, owner, status) even though no output schema exists, plus the single-filter constraint; it says nothing about pagination limits or total-count behavior, which the schema only partly 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?

Two short sentences, front-loaded with the filter axis, followed by return fields and endpoint. Nothing is padded and there is no ambiguity to untangle.

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-optional-parameter list tool with no output schema, the description supplies the missing return-value information and the filter cardinality constraint. Only pagination/total-result behavior is absent, and that is already visible in the schema.

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

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

Schema coverage is 100%, so both parameters are already documented, including the enum and the 25-per-page note. The description restates the enum values and adds the "one filter per call" meaning, but this is largely repetition of structured data, 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 tasks") plus the filtering axis and the returned fields, so it is clearly not the single-record get_task or the mutating create_task. It stops short of naming any sibling explicitly to disambiguate.

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 it should call this to enumerate tasks in a given status bucket. The parenthetical "one filter per call" rules out a multi-status request, which is a useful constraint, but there is no stated when-not or pointer 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral detail beyond them: matching is exact (no fuzzy/partial behavior), the full record is returned rather than a summary, and the call maps to GET /lookup.

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 verb and scope, ending with the return behavior. Slight redundancy with the schema on field values, but nothing that fails to earn 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 only three parameters, a full annotation set, and a description that covers exact-match semantics and the shape of the return ('full records'), an agent has what it needs to call this correctly. The lack of an output schema is partly offset by the return statement.

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 field, value and entity are all documented in the schema, making the 3 baseline appropriate. The description reinforces the allowed field values and the cf_ custom-field convention but adds no new semantics, and it never mentions the entity parameter that the schema defines.

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 concrete verb and resource — 'Exact-match lookup of contacts, companies or deals by one field' — and the qualifier 'exact-match' implicitly separates it from the fuzzy freshsales_search sibling. It stops short of naming that sibling or the freshsales_get_* tools explicitly, so the differentiation is inferable rather than stated.

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

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

'e.g. a contact by email address' gives one concrete usage scenario, and 'Returns the full records' hints that this is the way to fetch a complete record by a known key. But there is no explicit guidance on when to prefer this over freshsales_search or freshsales_get_contact, and no stated 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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real value beyond that: the returned fields (id, type, name, email), the per_page cap with a default of 10, and the underlying GET /search endpoint. It stops short of describing match semantics (prefix vs substring).

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 front-loaded sentences with essentially no waste; the searchable fields and return shape come first. The trailing 'GET /search' is minor implementation trivia 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 three-parameter read-only search with no output schema, the description covers what it searches, which entity types, what comes back, the result cap, and what to do with the returned id. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description restates the entity enum values and the per_page default without adding format or matching detail beyond the schema, which is the baseline case.

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 ('Search by name/email text') and enumerates the exact record types it operates on, plus what it returns. It is clearly a text-search tool rather than a list tool, though it does not name or rule out the sibling freshsales_lookup, so full sibling differentiation isn't achieved.

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 one useful routing instruction — 'Use the id with the get tools' — and constrains scope to 'one record type'. But it never says when to prefer this over freshsales_lookup or the freshsales_list_* tools, which an agent choosing among 30 siblings would need.

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=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the 'WRITE:' prefix is largely redundant. The one genuine addition beyond structured data is the partial-update guarantee ('only the fields you pass are changed'), which is meaningful. It says nothing about overwrite risk behind destructiveHint, permission requirements, or error behavior on invalid ids.

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 an endpoint reference, front-loaded with the WRITE signal and the key scoping rule. Nothing is 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 15-parameter mutation the description nails the update semantics and the schema documents every field, so an agent can call it correctly. Minor gaps remain: no mention that account_id must come from a lookup/list, and no output schema or note on what the call returns.

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% across all 15 parameters, including the tricky number_of_employees bucket codes and the cf_-prefixed custom_field object, so the schema carries the load. The description adds no parameter-level meaning beyond the general partial-update rule, which is the correct baseline-3 outcome.

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

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

States a specific verb (change fields of an existing account), the resource, and the HTTP operation, plus the '(company)' gloss that disambiguates 'account'. It is immediately distinguishable from create_account and get_account 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?

'change fields of an existing account' plus 'only the fields you pass are changed' tells the agent exactly when this applies (partial update of a record that already exists). It does not name alternatives such as freshsales_get_account for reading or freshsales_create_account for new records, so there are no 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 flag write/destructive/idempotent, and the description adds non-obvious behavior the agent cannot get elsewhere: partial-update semantics and the crucial warning that passing sales_accounts replaces the contact's associated companies. That is exactly the kind of 'what gets overwritten' context the annotations do not supply.

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

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

Front-loaded 'WRITE:' marker, then the core semantics, then the endpoint. One compact sentence plus a reference; 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?

Covers mutation type, partial-update behavior, the nested sales_accounts caveat, and the HTTP surface for an 18-parameter tool with no output schema. Minor gaps: it doesn't state what happens with an invalid contact_id or how clearing a field works.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the destructive replacement behavior of sales_accounts, which the schema only describes structurally. Other parameters rely on the schema, which is acceptable given full coverage.

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

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

States a specific verb ('change fields') and resource ('an existing contact'), which cleanly separates it from freshsales_create_contact (new) and from update_account/update_deal by resource. The PUT /contacts/{id} line confirms the target.

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?

Clear that this is for modifying an existing contact and that updates are partial ('only the fields you pass are changed'). It does not name alternatives or say when not to use it (e.g. use create_contact for new records), so it stops short of explicit routing.

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

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

Annotations already declare write, destructive, idempotent, and openWorld, so the safety profile is covered. The description adds genuinely non-redundant behavior: it is a partial update ("only the fields you pass are changed") and it maps to PUT /deals/{id}. It omits any note on the contact attach/detach semantics or permission requirements, which is why it isn't 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?

A single compact sentence pair with the WRITE intent and partial-update semantics front-loaded and the endpoint trailing. No filler and nothing an agent must wade through.

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 14 parameters fully described in the schema and no output schema, the description only needs to convey the update model, which it does via the partial-update statement. Missing: guidance on add_contact_ids/remove_contact_ids being additive rather than replacing the full contact set, which matters for a destructive write.

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%, including maxItems on the contact arrays and the currency caveat for amount, so the schema carries nearly all parameter meaning. The description only echoes deal_stage_id, amount, and expected_close as examples, adding no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("change fields of an existing deal") and leads with a WRITE marker plus the underlying PUT endpoint. The examples (stage move, amount, expected close) make it clearly distinguishable from freshsales_create_deal and freshsales_get_deal.

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?

Scopes usage to existing deals and names the motivating operations (stage change, amount, close date). It does not say when NOT to use it or point to a sibling such as freshsales_create_deal for new deals, so it stops just short of explicit alternative routing.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint. The description's word 'replace' usefully clarifies that the entire note text is overwritten rather than merged, which aligns with destructiveness, but it says nothing about irreversibility or what happens to other note fields/metadata.

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

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

Two short fragments, front-loaded with the mutation keyword; zero waste. The embedded HTTP path (PUT /notes/{id}) is marginally useful REST context rather than pure 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 2-parameter destructive mutation with rich annotations but no output schema, the description omits what the call returns and whether any other note attributes are affected by the replace. Adequate to call, 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 100%, so note_id and description are already fully documented in the schema. The description adds no format, id-source, or length guidance beyond that, 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 ('replace the text of an existing note'), which clearly separates it from freshsales_create_note and read-only get/list siblings. It stops short of naming those siblings explicitly, but the mutation 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?

The 'WRITE:' prefix and 'existing note' phrasing imply this is for notes that already exist (use create_note otherwise), but no explicit when-to-use/when-not guidance or alternatives are given.

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

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

Annotations already declare readOnly=false, destructiveHint=true, idempotent=true, and openWorld=true, so the safety profile is covered. The description adds the endpoint and status semantics, but leaves a real ambiguity: whether this is a partial update or a full replacement that clears omitted fields (PUT semantics), which is exactly the risk destructiveHint flags.

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 WRITE marker and the resource, then field specifics and the HTTP endpoint. No filler.

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

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

For a 6-param mutation tool with one required key and no output schema, the description is nearly complete. It lacks only the omitted-field/partial-update behavior, which matters given destructiveHint=true.

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 every field is documented with types, lengths, and status enum meaning. The description merely re-lists the same fields, adding no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (change/update) and resource (task) plus the exact editable fields and the numeric meaning of status. It is unambiguous against siblings like freshsales_create_task or freshsales_get_task.

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

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

The 'WRITE:' prefix and the field list imply this is for modifying an existing task, and the sibling name set makes create/get alternatives inferable. But there is no explicit when-to-use or when-not-to-use statement, nor any stated prerequisite (e.g., task must exist, required permissions).

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