SuiteDash MCP by usefulapi

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

Beyond annotations, it discloses important side effects: SuiteDash emails the primary contact a portal invitation when send_welcome_email is true, and create_primary_contact_if_not_exists conditionally creates a contact only when no existing contact has that email. Annotations already cover safety traits (write, destructive, open-world, non-idempotent), so this adds useful operational context without contradiction.

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

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

The description is front-loaded with 'WRITE', then covers core creation, conditional contact behavior, and the email side effect in a compact sequence. Every sentence adds actionable information with no filler.

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

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

For a create tool with a nested optional contact object and no output schema, the description covers the most consequential behavior: required fields, conditional contact creation, and an external email side effect. It leaves some gaps, such as role semantics and prevent_individual_mode, but is otherwise complete enough to call safely.

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

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

Schema description coverage is only 33%, so the description must compensate. It usefully explains the conditional behavior of create_primary_contact_if_not_exists and send_welcome_email, and confirms name/role are required, but it does not explain the role enum, prevent_individual_mode, or email format details beyond what the schema already shows.

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

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

The description states a specific verb and resource: create a CRM company. It also names required fields (name and role) and the optional primary contact, making it clearly distinct from sibling tools such as get_company, list_companies, update_company, and 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 clearly implies this is the tool for creating a company and gives explicit guidance for the send_welcome_email flag: leave it false unless the user asked. It does not explicitly name when not to use this tool versus siblings, but the creation-specific framing 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 cover the safety profile (destructiveHint=true, openWorldHint=true, idempotentHint=false), so the description's added value is the side-effect disclosure: the welcome-email flag causes SuiteDash to actually email the contact a portal invitation. It also explains the implicit company-creation behavior behind create_company_if_not_exists. Missing: whether duplicate contacts are merged/blocked and any auth/permission notes.

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

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

Four short sentences with no filler: write/identity first, requirements second, optional behaviors third, endpoint last. The 'WRITE:' prefix front-loads the most decision-relevant fact.

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

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

For a 15-parameter mutation with a nested address object and free-form custom_fields, the description covers the required fields, the key conditional flag, and the risky side effect; the schema carries the rest. No output schema exists, and the description doesn't say what a successful create returns (e.g., the new contact ID), which is the main remaining 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?

With 67% schema coverage, the description meaningfully supplements the schema by restating the cross-field dependency (email required unless role is Lead) and explaining how company_name pairs with create_company_if_not_exists. It leaves the remaining optional fields (tags, address, custom_fields) to the schema, which does describe them.

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

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

Opens with a specific verb+resource plus a 'WRITE:' marker ('create a CRM contact in SuiteDash'), which immediately separates it from the read siblings (get_contact, list_contacts) and from suitedash_update_contact. The endpoint (POST /contact) reinforces exact 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 real selection criteria inside the tool: email required except for Lead, link a company by name, and an explicit when-not ('leave send_welcome_email false unless the user asked for that'). It doesn't contrast against suitedash_update_contact or suitedash_create_company, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuinely useful behavior: it discloses the returned field set (which matters since there is no output schema) and signals that name matching is exact rather than fuzzy. Not-found/ambiguity behavior is not covered, keeping it below 5.

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

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

Two compact clauses, front-loaded with the resource and scope before the returned fields. The trailing REST endpoint is mildly redundant for an agent but cheap and cheaply placed.

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

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

A simple two-parameter read tool with full schema coverage and annotations carrying the safety profile; the description fills the one real gap (returned content, absent an output schema). Missing only edge-case behavior such as no-match or duplicate-name handling.

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 baseline by clarifying the matching semantics of 'identifier' as an exact name (the schema only says 'UID or name'), which materially affects how an agent should construct the call.

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

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

States a specific verb+resource ('Get company') and narrows scope to a single record retrieved by UID or exact name. It also enumerates the payload (primary contact, category, tags, address, custom fields), which lets an agent distinguish it from suitedash_list_companies. It does not explicitly name the sibling it supersedes, 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?

The 'one company by UID or exact name' phrasing implies a single-record lookup, so the when-to-use case is inferable, but no alternative is named (list_companies for browsing, get_company_fields for schema). The only explicit routing between tools lives in the schema's meta description, not in the tool description.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the returned content shape (type, required flag, allowed actions) and the underlying endpoint GET /company/meta, which helps the agent know what to expect without an output schema.

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

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

A single front-loaded sentence naming the resource and its contents, followed by a short endpoint reference. Every clause earns its place; nothing is padded.

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

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

With no parameters and no output schema, the description carries the burden of explaining the return value, which it does thoroughly (field categories, UIDs, type/required/actions). Minor omissions such as whether all fields are always returned or whether visibility filtering applies are the only gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The schema is empty and the description correctly adds no parameter guidance, matching the baseline for a no-arg tool.

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 resource (the company field schema for this account) and enumerates exactly what it contains: default and custom fields, public/private/target custom fields under UIDs, with type, required flag, and allowed actions. It is clearly distinct from sibling field tools like get_contact_fields and get_project_fields by virtue of the 'company' scope, though it never explicitly contrasts them.

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

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

There is no explicit statement of when to call this versus alternatives, nor prerequisites. However, the phrase 'under their UIDs' implicitly signals the intended use: discovering field identifiers before creating or updating a company. Usage is implied 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 usefully discloses the data surface returned (companies, tags, address, custom fields) and that lookup is by external identifier, but says nothing about not-found behavior, permissions, or rate limits. Adequate but not rich.

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 with zero waste: the payload contents come first, followed by the endpoint. No boilerplate or repetition of the title.

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

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

With no output schema, the description's enumeration of returned fields does real work in telling the agent what to expect. It is only slightly short of complete: miss/404 behavior and the fact that a non-primary email will not resolve are unstated, which matters for an openWorld lookup.

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 explains both identifier (UID or email) and meta (return field schema). The description's 'UID or primary email' restates rather than extends the schema, so the baseline 3 for full coverage applies. Note the description adds no hint of the 'primary' email qualifier's implications (e.g., non-primary emails not matching).

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 and resource ('One CRM contact') with the lookup keys (UID or primary email), the fields returned (companies, tags, address, custom fields), and the underlying endpoint GET /contact/{identifier}. It is clearly distinguishable from suitedash_list_contacts (many) and suitedash_get_contact_fields (schema).

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

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

Usage is implied: fetch a single contact when you already have a UID or email. There is no explicit statement about when to prefer suitedash_list_contacts for searching, nor what happens when no contact matches. The meta parameter's schema text does route agents to *_fields, but that guidance lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the scope is 'this account', the endpoint is GET /contact/meta, and the response shape (fields, types, required flags, allowed actions) is disclosed. It stops short of noting auth requirements or caching behavior, keeping it at a 4 rather than 5.

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

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

Two sentences, both front-loaded with the highest-value information (what the schema contains first, the UID usage note second). Every clause carries information; the endpoint reference is compact and useful.

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

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

There is no output schema, so the description must convey the return payload — and it does: each field's type, required status, and permitted actions. For a zero-parameter read tool with safety already declared in annotations, nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed and redirects the parameter discussion to how the OUTPUT values (UIDs) are used in other tools' custom_fields.

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

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

States a specific verb+resource ('contact field schema of this account') and enumerates what it contains: default and custom fields with type, required flag, and allowed actions. The 'contact' qualifier separates it from get_company_fields and get_project_fields without opening their schemas.

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 second sentence gives useful downstream guidance — custom fields appear under their UID and those UIDs are what to pass in custom_fields — which implies the tool should be consulted before create/update calls. However, it never explicitly says when to call this versus suitedash_get_contact, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the returned field set and the route, but says nothing about what happens when no match is found, whether 'most_recent' sorts by creation or update, or any rate/consistency behavior.

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

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

Two sentences, front-loaded with the payload contents, then lookup modes and the route. Efficient overall; the literal endpoint string is mildly technical noise for an agent but reinforces the lookup path.

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, enumerating returned fields is doing real work, and the lookup-variant explanation covers the main ambiguity. Adequate for a single-record read; only the empty-result behavior is left unstated.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the meta opt-out. The description restates the lookup modes ('UID (default), exact name, a name fragment, or the most recent one') without adding default syntax, matching rules, or ambiguity handling beyond what the schema provides — 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?

The description names a specific resource ('One project') and enumerates what comes back (description, clients, teammates, team, leader, economics, custom fields), plus the underlying route. It is clearly a single-record fetch and thus implicitly distinct from list_projects, but it never names that sibling, so differentiation is left to inference.

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

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

It explains how to locate the record (UID default, exact name, fragment, most recent), which is useful but is really parameter guidance. There is no explicit statement of when to call this versus list_projects or the *_fields tools, and no prerequisites or error conditions are mentioned.

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

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

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful behavioral context by explaining the returned content: default and custom project fields keyed by UID with type, required flag, and allowed actions.

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?

Extremely concise and front-loaded: it names the resource and summarizes the returned schema in one sentence, followed by the endpoint. No wasted text.

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

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

There is no output schema, so the description must explain return content. It does so adequately by naming default/custom fields under UIDs with type, required flag, and allowed actions, though it does not describe the exact response container shape.

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 parameter semantics have limited burden. The schema is empty and consistent with the description; no parameter explanation is needed.

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 resource: the project field schema for the account, including default/custom fields and their metadata. The resource name distinguishes it from company/contact field tools, but the description does not explicitly differentiate among those 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?

Describes what the tool returns but gives no guidance on when to use it, when not to use it, or how it relates to sibling tools like get_company_fields or get_contact_fields. Usage is only implied by the subject matter.

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 genuinely non-obvious behavior: a hard 10-per-page page size, and that idle companies are excluded from results — a data-visibility caveat the agent cannot learn from the schema.

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

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

Two dense sentences plus the endpoint: record fields first, then capabilities, then transport. No filler, and the page-size constraint is front-loaded.

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

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

With no output schema, the description usefully enumerates return fields and pagination size. It leaves the pagination continuation (next_page) implicit, though the page parameter schema hints at it, and it does not say what totals/metadata come back.

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 80%, so the baseline is 3, but the description adds natural-language meaning by tying created_after/created_before to filtering and by stating that sorting is by name or creation date, effectively explaining the order_by enum. It does not mention page or meta, which the schema already covers.

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 CRM companies") and enumerates exactly what each record contains plus the supported filter/sort, which makes the listing role obvious against get_company. It never explicitly names a sibling, so it stops short of full 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?

Usage is implied by the capability sentence: use it when you want a filtered, sorted page of companies. There is no explicit routing advice (e.g. to get_company for a single record, or to list_contacts for another entity), so the agent must infer alternatives from sibling names.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds page size (10) and the GET path, but says nothing about total counts, rate limits, or ordering defaults beyond what the schema shows.

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 what it returns before the filter/sort clause. No filler, though the field enumeration is slightly dense.

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

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

With no output schema, the description usefully enumerates returned fields (name, emails, phones, role, tags, companies, address, custom fields) and notes paging size. Adequate for a read-only list tool; only missing cursor/total behavior.

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

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

Schema coverage is 80%, so baseline is 3; the description earns an extra point by explaining that creation-time filtering exists and that order_by supports name or creation date, which compensates for the enum-only order_by parameter having no schema description.

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

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

States a specific verb and resource ('List CRM contacts') and clarifies the entity subtypes (leads, prospects, clients) plus the returned fields. It is distinguishable from get_contact by being an enumerating list, though it never names the sibling explicitly.

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

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

Usage is implied by 'List' plus the filtering/sorting clause, but there is no explicit guidance on when to use this versus get_contact or list_companies, and no note on how to paginate beyond the schema's next_page hint.

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, openWorldHint=true, so safety is covered; the description adds useful behavior: page size of 10, filterable by creation time, sortable dimensions, and the underlying GET /projects endpoint. It does not mention rate limits or how pagination terminates, but adds real context beyond annotations.

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

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

Three short sentences, front-loaded with the resource and page size, then capability, then the alternative tool. No filler and nothing buried.

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

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

With no output schema, the returned-field list is valuable, and the creation-time filter plus sort dimensions round out the picture. Minor gap: nothing about total page counts or how next_page feedback works, though the schema's page description covers that.

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 80%, so parameters are already well documented; the description's mention of sorting by name, creation, start or end date simply restates the order_by enum. It adds no syntax or format detail for created_after/created_before and says nothing about the meta flag, so it sits at the baseline.

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

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

States a specific verb and resource ("List projects") and enumerates the fields returned: name, status, start/end dates, due time. It also names the sibling it is not (suitedash_get_project) with the reason, so an agent can distinguish it without opening another 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?

Explicitly routes detail work to suitedash_get_project ("client, team and economics") and states the filtering/sorting capability of this tool. It gives clear context for use but no explicit when-not conditions beyond the sibling pointer.

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/non-destructive, so the safety profile is covered; the description adds the meaningful extras — pagination shape (10 per page), the licensing gate and its 403 failure mode, and the underlying GET /worlds endpoint. It doesn't describe the response payload, so not 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 front-loaded sentence plus the endpoint; every clause (resource, grouping clarification, page size, prerequisite, error code) carries information an agent needs.

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?

Low-complexity read tool with 2 optional params and no output schema; the description plus schema tell the agent how to page and what gate to expect. The one real hole is that nothing explains the `order_by` enum values, and the response shape is only implied by the schema's next_page reference.

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 50%: `page` is well documented in the schema, but `order_by` (with its six-value enum) is undocumented in both schema and description. The description only reinforces page size, so it does not compensate for the enum gap — 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 ('List the account's Worlds') and disambiguates the term with '(client groupings)', plus page size. It never names a sibling tool, so it stops short of the 5 bar for explicit sibling differentiation, but an agent can tell it apart from list_companies/list_contacts on resource alone.

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

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

Gives a concrete availability precondition: requires the WORLDS Power-Up, otherwise the API returns 403. That is a real when-not-to-use signal. It doesn't route to any alternative or say what to do on 403, so no 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds crucial context: unknown emails may be created as marketing contacts, and subscription can trigger campaigns or automations. It also states the reply carries per-person outcomes and cites the underlying POST endpoint, which is more than the annotations provide.

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

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

One front-loaded paragraph beginning with 'WRITE:', every sentence adding distinct value: action, scope, side effects, consent gate, return format, endpoint. No repetition or 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?

Given a single parameter object, no output schema, and destructive/idempotent annotations, the description covers the behavioral risk, side effects (contact creation, campaign triggering), consent requirements, and return shape. An agent has everything needed to call it safely.

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 schema description coverage at 0%, the description must compensate. It clarifies that subscribers are identified by email and that audiences are numeric ids from SuiteDash > Marketing, which adds useful meaning. However, it does not document the optional first_name/last_name fields or the 50-item batch limits, leaving part of the schema unexplained.

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

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

The description states a specific verb and resource: 'subscribe people (by email) to one or more marketing audiences'. It also scopes the resource precisely ('numeric audience ids from SuiteDash > Marketing'). No sibling tool does marketing subscription, so it is clearly differentiable.

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 explicit when-and-when-not guidance: only for people who have consented, and only when the user explicitly asked. That is a strong usage gate for a write that enrolls real people into campaigns.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely useful mechanics: only passed fields change, null clears a value, and tags/custom fields wholesale replace existing values. That replacement warning is exactly the destructive behavior an agent must know before calling; only auth/rate-limit context is missing.

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 compact sentence with the operation class, target, lookup key, three behavioral rules, and the HTTP route — no filler and all critical constraints front-loaded.

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

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

Given 13 parameters, a nested address object, and no output schema, the description covers the essentials: identification, partial semantics, null-clearing, replacement of collections, and the endpoint. The only omission is what the call returns (updated company vs. acknowledgement), which an agent might want to confirm the update.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: partial-update behavior for the whole payload and the fact that custom fields (whose schema description only covers key/value typing) are replaced rather than merged. The 13-parameter surface is otherwise handled by per-field schema descriptions.

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

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

States a specific verb ('update fields'), resource ('existing CRM company'), and lookup key (UID or name), immediately distinguishing it from create_company and get_company siblings. The 'WRITE:' prefix signals the operation class 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?

Usage is implied by 'update fields of an existing CRM company' plus the lookup semantics, so an agent knows to reach for it when the record already exists. However, it never names alternatives (create_company for new records, get_company_fields for discovering custom-field UIDs) or states prerequisites, leaving routing 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?

Goes well beyond the annotations (which only flag destructive/idempotent/openWorld): it discloses that tags and custom_fields are whole-value replacements rather than merges, that null is the explicit clear signal, and that send_welcome_email triggers a real outbound portal invitation email only when none was sent before. Those are exactly the side effects and destruction semantics an agent must know before calling.

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

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

Four tight sentences, front-loaded with the write verb and resource, followed by the highest-risk behaviors (replacement, email side effect) and the endpoint. No filler or restatement of the title.

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

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

For a 20-parameter nested mutation with no output schema, the description covers the destructive and side-effect risks an agent needs. It does not say what the response contains or whether the identifier changes if email is updated, which is a modest remaining 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 coverage is 75%, and the description adds the cross-cutting semantics the schema cannot express per-field: partial-update behavior, null-as-clear, replacement semantics for tags/custom_fields, and the send_welcome_email guard. It does not explain identifier format nuances or the interaction between email and identifier beyond the schema's own note.

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

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

States a specific verb and resource ('update fields of an existing CRM contact') plus the lookup key (UID or email), which cleanly separates it from suitedash_create_contact and suitedash_update_company. The 'WRITE:' prefix plus the PUT endpoint make the operation unambiguous at a glance.

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

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

Gives clear operational context: only passed fields change, null clears, and send_welcome_email should be left unset unless the user explicitly asked. It does not explicitly name create_contact as the alternative for new records, but 'existing contact' implies the boundary well enough.

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 this as write, destructive, non-idempotent, and open-world. The description adds useful context: partial update semantics, status validation against account statuses, HTML support in text fields, and the PUT endpoint; it does not detail permissions or irreversibility, so it is strong but not exhaustive.

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

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

Dense and front-loaded: 'WRITE' and the core action are stated first, followed by lookup, partial-update, status, HTML, and endpoint details. Every sentence carries actionable information with little waste.

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

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

For a 14-parameter destructive mutation with nested custom fields, the description covers the key behavioral constraints and helper tool while annotations and schema carry safety and parameter detail. It could say more about permissions or irreversibility, but overall it is sufficiently 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 parameter meaning is already well documented. The description mostly mirrors lookup and status details already present in the schema, adding only the status-field reference and HTML note; custom field structure is left to 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 ('update fields of an existing project') plus the lookup modes and partial-update behavior. This clearly distinguishes it from create/get/list siblings.

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

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

Explains that it is for existing projects, supports UID/name/name-fragment/most-recent lookup, and notes that only passed fields change. It also points to suitedash_get_project_fields for status values, though it does not give explicit when-not guidance or a direct alternative.

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