Boomerang

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

Adds substantial behavior beyond the annotations: roles are additive ('Existing roles are preserved — new roles are added incrementally'), and the dormant-Super-Connector path discloses a consequential side effect ('starts their automations and uses a plan seat', irreversible back to DORMANT) plus user-facing copy constraints. Minor deduction because the irreversibility notice sits next to destructiveHint=false, which an agent could read as low-stakes; a one-line warning would sharpen that contrast.

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

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

Front-loaded with the core action, but the Super Connector onboarding exclusion is restated three separate times (main paragraph, 'When to use', and the optional prerequisite), and the user-facing copy rule appears twice. The signal is strong but the redundancy inflates length notably.

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?

Output schema exists so return values need no explanation, and prerequisites, valid enums, and mutation semantics are all covered. Slight gap: the description says workspace_id/user_id are injected from headers while user_id is also an explicit schema parameter with default null — an agent could be unsure whether to pass user_id or rely on injection.

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 0% and the raw schema is untyped ('role' is an untyped array, no enum, no descriptions), so the description carries the full burden — and it does: it enumerates all six valid role values, explains user_id is an internal keycloak UUID, and clarifies super_connector_state=ACTIVE usage. This is exactly the compensation the low coverage requires.

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 ('Assign one or more workspace roles to an existing user by user_id') and immediately scopes what it does NOT do (profile fields, Super Connector category). It explicitly distinguishes itself from add_super_connector and create_workspace_member, so an agent can route correctly without opening sibling 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?

Provides explicit when-to-use ('ONLY after the person exists in the workspace'), when-not-to-use ('Do NOT call on add-member form submit', 'Do NOT use for new Super Connector onboarding'), and names the correct alternative (add_super_connector). Prerequisites section adds a verification path via create_workspace_member response.

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 idempotent/non-destructive/non-open-world, but the description adds substantial behavior beyond them: side effects (platform user creation, role assignment, ledger provisioning), a required prerequisite check, the ALWAYS-required name rule that is not auto-filled, and a warning not to call speculatively with blank fields.

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

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

Front-loaded with the core effect and structured into Use when / Behavior / Prerequisites / Returns sections, which is easy to scan. It loses a point for redundancy: the 'do NOT call create_workspace_member or add_role' prohibition appears twice, and the numbered form steps restate earlier content.

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

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

An output schema exists, so return values need not be explained, and the description still summarizes category_ledger_results. Combined with annotations, prerequisite instructions, and the multiple-result handling rule, an agent has everything needed to invoke and follow up correctly.

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

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

With 0% schema description coverage, the description carries the burden and does document five of seven params (email, first_name, last_name, linkedin_id, category_ids) including their required status and a warning about naming. However, notes and super_connector_tier are never mentioned, leaving two params completely uninterpretable.

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?

Names a specific verb+resource and elaborates the compound effect: 'Add a Super Connector... creates the platform user if needed, assigns the Super Connector role, and places them in the selected category'. It explicitly distinguishes itself from create_workspace_member and add_role, so an agent can route without opening sibling 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?

Explicit when-to-use ('Use whenever an admin adds a new Super Connector'), explicit when-not ('This is the ONLY tool... do NOT use create_workspace_member or add_role'), and an ordered pre-requisite (call get_workspace_categories first). Nothing is left 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 only cover read-only safety; the description adds substantial behavioral context beyond them: the COUNTING RULE (COUNT_DISTINCT vs COUNT inflation), GROUP-BY HYGIENE (ID+NAME to surface name-casing duplicates), a QUALITY vs VOLUME caveat about low-confidence paths, and a required user-confirmation step when multiple records return. These are real gotchas an agent could not infer from 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?

Well front-loaded with 'Group, count, and rank' and section labels ('Use when', 'Behavior'), and the high-value rules are called out in caps so they are scannable. It is dense and long, but for a 9-parameter aggregation endpoint most sentences earn their place; a few phrases overlap between the COUNTING rule and QUALITY vs VOLUME sections.

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 complex 9-param tool with nested filter/metric objects and an output schema, the description covers the counting rule, filter composition semantics, threshold clauses, pagination, sorting intent, and a follow-up safety instruction. Since an output schema exists, it correctly does not need to enumerate return fields.

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

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

Schema coverage is moderate (56%), and the description compensates by explaining the semantic use of several parameters: having for post-aggregation thresholds, multiple FilterGroups for OR, page_token + next_page_token for pagination, and limit for top-N. Some fields (entity, sort, joins, metrics) remain largely delegated to the schema, so it adds meaningful but not exhaustive parameter guidance.

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 specific verbs and resource: 'Group, count, and rank records across any Boomerang entity', and repeatedly distinguishes this aggregation role from lookup/paging behavior ('never page through raw relationship rows', 'reads like a lookup but is really group ENTITY_RELATIONSHIP by source user'). An agent can tell it apart from search_warm_intro_relationships or search_accounts_with_filters without opening other 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?

Explicit when-to-use ('counting, ranking, grouping, breakdowns, and threshold questions'), an extensive TRIGGER PHRASES list, and a concrete KEY PATTERN for the ranked-by-source-filtered-to-one-target case. It also names when-not ('always use Aggregate for this, never page through raw relationship rows') and routes sub-cases to the right parameters (having, multiple FilterGroups, page_token).

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?

Adds substantial behavior beyond the annotations (readOnly=false, openWorld=false, idempotent=false, destructive=false): non-existent tag names are auto-created, matching is case-insensitive, and assignment is additive so existing tags are preserved. It also discloses that workspace_id/user_id are injected from headers, which the schema never 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?

Front-loaded with the core action and behavior, which is good, but it then spends lines spelling out the return fields ('Returns entities[] with fields: entity_id, tags...') that an output schema already covers, adding redundancy rather than value.

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

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

Given the output schema exists, the description doesn't need to explain return values (though it redundantly does). For a mutation tool it adequately covers auto-creation, case-insensitivity, additive behavior, and header-injected context, leaving only the parameter format 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 0%, so the description carries the full burden, yet it barely explains the three parameters. It only offers 'Single assignment = one entity id and one name' and mentions entity types informally; it never clarifies the accepted entity_type values or the array semantics of tag_names/entity_ids.

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: 'Attach tags by name to one or more entities (accounts, contacts, workspace members).' It distinguishes itself from the tagging siblings (create_tag, get_entity_tags, remove_entity_tags) by declaring itself the preferred tagging path and noting CreateTag is unnecessary.

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?

Explicit 'Use when: Preferred way to tag entities' guidance, and it names the alternative it replaces ('no need to call CreateTag first'). It covers single vs bulk but does not state when NOT to use it (e.g., switching to remove_entity_tags for removal), so it stops 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?

Goes well beyond the annotations by disclosing side effects annotations cannot express: adding CUSTOMER removes PROSPECT unless PROSPECT is in the same call, re-adding an existing category is a no-op, and accounts with unknown UUIDs are skipped and surfaced in skipped_account_ids. Return shape and skip conditions are stated outright.

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-loads the core behavior, then rules, then return contract, then a separate 'Use when' block. Dense but every sentence carries distinct information — no restatement of the name 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?

For a two-parameter bulk mutation with an output schema, the description still covers inputs, side effects, skip semantics, and call prerequisites. Nothing material to invoking it correctly is left to inference.

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

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

Schema description coverage is 0% and neither parameter has a description, so the description must compensate entirely — and it does: it enumerates the legal category values and states that account_ids are internal UUIDs. It also explains that workspace_id/user_id come from request headers, which clarifies why only two params exist.

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 one or more categories to one or more accounts') plus the key distinguishing modifier 'keeping the categories they already have', which separates it from bulk_set_account_category and bulk_remove_account_categories. The valid category vocabulary is spelled out, so the resource is fully concrete.

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?

Explicit 'Use when' section with natural-language triggers ('Acme is a Partner too', 'tag these as Competitor as well') and an explicit prerequisite workflow: resolve account UUIDs first via search_accounts_with_filters or get_accounts_by_ids, never guess them. The additive-vs-replace distinction from the bulk_set sibling is implied by the first sentence.

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

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

Annotations already declare destructiveHint=true, but the description adds genuinely new behavior: the updated_count/skipped_account_ids return contract, the precise skip rule (id not in workspace), the uncategorised edge case when all categories are removed, and the header-injected workspace_id/user_id. This is exactly the context an agent needs beyond the annotation.

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

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

Front-loaded with the core action, then cleanly sectioned into 'Use when' and 'Behavior'. Every sentence carries information, though the standalone 'Behavior: destructive' line merely restates the destructiveHint annotation.

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?

Output schema exists so return values needn't be explained, yet the description helpfully names updated_count and skipped_account_ids. Coverage is strong for a destructive mutation; the only real gap is the identifier type for the categories parameter and the effective requirement that both arrays be supplied.

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 0% and both parameters are bare untyped anyOf arrays with null defaults and no required fields, so the description has to carry the load. It clarifies that account_ids are internal UUIDs, but never states whether categories are names or IDs, nor that both arrays are effectively required despite the schema showing no required parameters.

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

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

States a specific verb and resource ('Remove one or more categories from one or more accounts') plus the crucial scope nuance that other categories are preserved and accounts are identified by internal UUID. This clearly separates it from bulk_add_account_categories and bulk_set_account_category.

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?

Has an explicit 'Use when' clause with two concrete user utterance examples ('Acme is no longer a Customer', 'remove Competitor from these'), plus a directive to resolve UUIDs first via search_accounts_with_filters or get_accounts_by_ids and 'never guess them'. Both the trigger condition and the prerequisite 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?

Goes well beyond the destructive annotation by explaining that this is a replacement operation that removes every category not listed, describes the legacy single-value fallback behavior, and clarifies that skipped_account_ids indicate bad ids rather than write failure. It also notes workspace visibility and that the write is visible to every user, which is valuable behavioral context for a destructive 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?

Despite being detailed, the description is front-loaded with the core replacement semantics and structured into behavior, alternatives, prerequisites, and confirmation guidance. Every sentence contributes useful information for a destructive bulk operation.

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

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

Complete for a complex destructive tool: it explains replacement semantics, valid categories, parameter fallback behavior, UUID resolution, skipped-id meaning, workspace visibility, and sibling alternatives. The output schema exists, and the description still helpfully clarifies updated_count and skipped_account_ids.

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?

Although schema description coverage is 0%, the description fully compensates: it explains that categories is the full set, category is the older single-value form used only when categories is empty, and accounts are identified by internal UUID rather than name or CRM id. This gives clear semantics for all three parameters.

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

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

States a specific verb (replace) and resource (account categories) and precisely describes the resulting state: each account ends up with exactly the listed categories. It also distinguishes itself from the add/remove category siblings, so an agent can select 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?

Gives explicit when-to-use guidance with examples ('move Acme to Prospect'), names the sibling alternatives for adding or removing categories, and instructs how to resolve account UUIDs first. It also adds a confirmation safeguard for ambiguous searches, which is highly actionable.

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 past the annotations: discloses the dedup precedence chain (CRM reference id, then LinkedIn company id, then LinkedIn handle), that a match returns the existing account instead of erroring, that category defaults to Prospect/DEFAULT, and that output rows may not correspond to input order and may be fewer than inputs. Also states header-injected workspace_id/user_id and adds an explicit multi-result handling instruction.

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?

Well front-loaded with scannable 'Use when' / 'Behavior' / 'Returns' sections and no filler prose. The inline return-field list is partly redundant given an output schema exists, and the trailing IMPORTANT paragraph is long, but each block carries distinct 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 bulk mutation with no required params, the description covers the hard parts: dedup resolution, partial-result rows, ordering guarantee, and default fan-out. What's missing is failure behavior for invalid rows or partial-batch failures, which matters for a destructive, non-idempotent bulk 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 0% and the single parameter is an array of objects with ~11 nested fields, so the description must compensate. It explains category/category_source semantics, the DEFAULT-to-Prospect fallback, and hints at the role of reference_id/linkedin_url via the dedup rules, but leaves name, website, city, state, country, and linkedin_url format completely undocumented.

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 with scope: 'Create one or more accounts in bulk', then pins down the batch semantics (mixed category_source per row). An agent can tell this is the bulk-creation path rather than a category-mutation path, though it never names a sibling explicitly to close the loop.

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?

Explicit 'Use when' clause with concrete triggers (CSV upload, list of company names), plus one hard constraint: 'Setting category requires setting category_source alongside it.' No when-not guidance or pointer to search_accounts_with_filters for accounts that already exist, so it falls short of a 5.

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

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

Annotations declare a non-readOnly, non-idempotent, non-destructive write, and the description notes header-injected workspace_id/user_id. It does not explain whether re-mapping an existing field overwrites it, how conflicts are resolved, or what the response contains. With annotations covering the mutation profile, this is 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?

Tightly front-loaded: one sentence of purpose, one 'Use when' sentence with an example, one note on injected params. No waste, though the injected-header note is terse.

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?

Output schema exists so return values needn't be explained, and annotations cover the write profile. But with 0% schema description coverage on five parameters, the description leaves key inputs (data_type, crm_specification_id, requiredness) undefined, which is 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 coverage is 0%, so the description must compensate, but it only mentions canonical vs external field names and object type. It does not explain data_type, crm_specification_id, or that all 5 params default to null and are effectively required in practice — a significant gap for a 0% coverage schema.

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

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

States a specific verb+resource and scope: mapping a Boomerang canonical field to the connected CRM's field name for a given object type. This is clearly distinguishable from sibling create_crm_prepared_statement and create_crm_specification.

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?

Explicit 'Use when' section names the prerequisite (after create_crm_specification) and the exact trigger condition (when a prepared statement's SELECT needs to reference a CRM-native field name that differs from the canonical name), with a concrete example.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false, openWorld=false), it discloses real behavior: the statement_key enforces a hardcoded required variable server-side, missing-variable failures surface as FAILED_PRECONDITION and should be retried, and workspace_id/user_id are injected from request headers. It also adds the multi-record handling rule requiring the user to choose.

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-loads purpose, then usage, then failure handling, which is a sensible order. The 'Returns variables[] with fields' block largely duplicates the input schema and the existing output schema, making it the one section that does not fully 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?

For a 7-parameter create with an output schema present, it covers sequencing, header injection, the required-variable contract, retry on failure, and multi-result handling. The main gap is the undocumented object_name/description/crm_specification_id parameters.

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 14% across 7 parameters, so the description must compensate. It documents the variables[] item shape (name, data_type, required, default_value, description), statement_key, statement_text, and statement_format, but leaves object_name, description, and crm_specification_id semantics unexplained. Partial compensation only.

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 (Define) and resource (a named CRM query/mutation keyed by statement_key) for a registered CRM specification, and names the native formats (SOQL, REST_JSON). It also distinguishes itself from the sibling create_crm_specification by positioning this as the follow-up that defines how a specific check runs.

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 says to use it after create_crm_specification and gives a concrete example (GET_CUSTOMER_ACCOUNTS_BY_IDS). It also documents the retry path when FAILED_PRECONDITION names a missing variable. It stops short of naming when NOT to use it or 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 declare readOnlyHint=false and idempotentHint=false; the description reinforces this by saying to register 'once per CRM connection' and that it returns an id consumed downstream. It also clarifies the ownership semantics of connected_user_id and that workspace_id/user_id come from headers. Good added context, though it doesn't state auth requirements or failure 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?

Purpose and its downstream id dependency are front-loaded, followed by a clearly delimited 'Use when' block. Efficient and scannable; the header-injection note is slightly tangential but still 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?

An output schema exists, so return values needn't be explained, and the description still notes the id it returns. Ordering/usage and one parameter are covered; the missing piece is the meaning of connection_source, keeping it just short of fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It usefully disambiguates connected_user_id ('the Boomerang user who owns the integration, not a CRM record id') and clarifies that workspace_id/user_id are header-injected (not schema params), but connection_source is never explained. Partial compensation for two undocumented parameters.

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

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

States a specific verb+resource ('Register a CRM connection (Salesforce/HubSpot) for a workspace') and names the exact sibling tools that depend on its returned id (create_crm_prepared_statement, create_crm_field_mapping), distinguishing it from get_crm_specification and the other CRM 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?

The 'Use when' block is explicit: once per CRM connection, and before defining any prepared statements or field mappings for it. It gives both the frequency constraint and the ordering dependency, 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 declare readOnly=false, destructive=false, idempotent=false, openWorld=false, so the write/safety profile is already covered. The description adds real value beyond that: workspace_id/user_id are injected from headers, and the IMPORTANT block instructs the agent to present multiple records as options and not auto-act. It does not warn about duplicate creation despite idempotentHint=false.

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

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

Front-loaded with purpose, then usage, then delivery guidance in a logical order; the multi-result caution is correctly placed last. The middle "Returns items[] with fields" block is redundant with the existing output schema and its formatting is noisy, which keeps it from a 5.

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

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

With an output schema present and annotations covering safety, the description only needs to fill contextual gaps — and it does: header-injected identifiers, the semantics of the created path, and the human-in-the-loop rule for multi-record responses. The one missing piece is any note on duplicate/dedup behavior given idempotentHint=false.

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 and the schema already documents each nested field including the relationship_type-conditional requirements for target_account_id/target_contact_id. The description only adds that workspace_id/user_id come from headers, which is context not tied to a declared parameter.

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

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

States a specific verb+resource (create self-declared relationship paths) and immediately names the two concrete artifact types produced (SELF_DECLARED_ACCOUNT / SELF_DECLARED_CONTACT) and their downstream use (surfacing warm intros). This lets an agent distinguish it from siblings like search_warm_intro_relationships or add_super_connector 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?

An explicit "Use when:" block scopes the tool to a super connector asserting a personal relationship, and crucially names the exclusion condition — relationships not auto-detected via calendar or LinkedIn. It stops short of naming a concrete alternative tool to reach for instead, so it is clear but not fully routing-aware.

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, idempotent=false and openWorld=false, so safety is covered. The description adds genuinely new behavioral context: the case-insensitive uniqueness constraint per entity type and the fact that workspace_id/user_id come from request headers rather than arguments.

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

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

Front-loaded with purpose, then usage, then mechanics. The closing sentence about 'pagination info' is extraneous and awkward for a create operation, costing it a point.

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 mutation tool with annotations and an output schema, so safety and return shape are largely covered elsewhere. The description handles the routing question and header-injection mechanics well; only entity_type semantics remain thin, which is a minor 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 0%, so the description must compensate. It explains name uniqueness and that workspace/user identity is header-injected, but says nothing about accepted entity_type values or name format constraints, leaving half the parameters under-specified.

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

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

States a specific verb and resource ('Create a workspace tag for an entity type') plus a scoping rule (unique per entity type, case-insensitively) that separates it from the sibling assign_tags_by_name. An agent can identify the tool's job 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?

Contains an explicit 'Use when' clause with a negative condition ('you are not attaching it to anything') and names the preferred alternative (AssignTagsByName) for the other case. Routing is unambiguous.

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 signal a non-idempotent, non-destructive write, but the description adds substantial behavioral context beyond them: the WORKSPACE_MANDATORY vs WORKSPACE_OPT_IN activation semantics (runs for everyone, no per-user opt-in), the requirement to copy template_id/trigger_kind/metadata verbatim and never invent event slugs, and the note that workspace_id/user_id are injected from request headers.

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 purpose and the two kinds are front-loaded, and the 'Use when:' block is clearly delimited. It is long and occasionally repetitive ('draft metadata.preview' appears twice, template instructions are restated), but for a 17-param tool with two modes and several creation flows most sentences carry necessary conditional logic.

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 the tool's complexity (17 params, two trigger kinds, template inheritance and opt-in flows), the description is complete: an output schema exists so return values needn't be covered, and the mutation/safety profile is already carried by annotations. Nothing an agent needs to invoke it correctly across the enumerated paths 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 0%, so the description carries the full burden across 17 params. It explains the meaning of most of them (cron vs one_time_fire_at mutual exclusivity, scope USER|WORKSPACE, activation_mode values, trigger_kind, template_id, catalog_id creating a USER activation, metadata.preview/supported_events, description length cap and 'never copy the prompt'). A few params (plan, audience_type, audience_filter, agent_thread_id, channel_metadata) go unmentioned, hence not a 5.

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

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

Opens with a specific verb+resource ('Create a workflow trigger for a recipient') and immediately partitions the tool into its two operating kinds (SCHEDULED vs WEBHOOK), which lets an agent distinguish it from updateWorkflowTrigger and the list tools. The scope is precise enough that no schema inspection is needed to know what the tool produces.

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

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

Has an explicit 'Use when:' block covering three concrete scenarios (new reminder/schedule, event-driven notification, opt-in activation of a WORKSPACE_OPT_IN template). Names alternatives and their boundaries: it says to call listTriggerTemplates first, list_workflow_triggers first to avoid duplicates, and explicitly warns 'do not use updateWorkflowTrigger for first-time opt-in'.

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: discloses upsert-by-email semantics, that it creates the platform User if needed, that it does NOT assign roles, that it returns an internal keycloak_user_id (and warns never to expose it), and confirms idempotency. Annotations only cover the safety profile; the description adds the operation's real 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?

Purpose and constraints are front-loaded, but the text is heavily bloated with duplicated directives (the Super Connector exclusion and the 'never call add_role on form submit' rule each appear multiple times) and with extensive user-facing copy scripting that crowds out the operational essentials.

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 complex multi-step tool with an output schema present, the description covers prerequisites, the confirm-before-call requirement, and post-success next steps. Minor noise such as 'returns pagination info' on a single-member create is odd but does not block correct invocation.

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 0% and the schema types are unusual (first_name/last_name as objects, no required fields), so the description carries the burden and does so for most parameters — email as the required upsert key, and First/Last Name, Phone, LinkedIn URL as identity fields. It omits member_profile and conflicts slightly with the schema by calling fields 'required' when none are, but overall it adds substantial meaning.

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 ('Add or update a ... workspace member') and immediately differentiates itself from siblings by scope ('non–Super Connector', upserts by email). An agent can distinguish it from add_super_connector, add_role, and update_workspace_member without opening 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?

Gives explicit when-to-use and when-NOT-to-use conditions (Super Connectors → add_super_connector), plus concrete step-by-step ADD and UPDATE flows with the alternative search_workspace_members named for the no-email case. Nothing is left 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?

The description asserts 'Idempotent — a missing row returns deleted=false,' but the annotations declare idempotentHint: false. That is a direct contradiction on a named behavioral hint and will give the agent conflicting signals about safe retry behavior. (The other content — soft-delete with audit history preserved, header-injected identifiers — is genuinely useful, but the contradiction dominates.)

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

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

Front-loaded with the action and scope, then organized under 'Use when' and 'Behavior' labels. Slightly fragmented into stubs, but every line 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?

With an output schema present, return details need not be explained, and the destructive nature is covered by both annotations and the 'Behavior: destructive' line. The description adds soft-delete/audit context and the header-injection note, leaving only the meaning of scope/scope_id under-specified.

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 0% and neither of the two parameters (scope, scope_id) is documented in the schema; there are no enums to infer from. The description only gestures at the concept ('USER or WORKSPACE scope') and mentions that workspace_id/user_id are injected from headers, but never states the accepted scope values or what scope_id refers to, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource with its exact scope: 'Delete the single MEMORY document for a USER or WORKSPACE scope.' It names the sibling it is not (UpsertScopedMemory) and is immediately distinguishable from get_scoped_memory and upsert_scoped_memory.

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 an explicit trigger ('Use when the user explicitly asks to clear their scoped memory') plus an exclusion and alternative ('Prefer UpsertScopedMemory to update, not delete-then-recreate'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: that the response is workspace-specific, that workspace_id/user_id are injected from headers (no auth params needed), and the multi-record handling rule to present options to the user before acting.

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

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

It is well-structured with labeled 'Use when', 'Behavior', and 'Returns' sections and front-loads the core purpose. There is some redundancy in restating the live/not-hand-maintained point, but overall it is appropriately sized and each section carries meaning.

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 an output schema present, the return-value detail is partly redundant, but annotations cover the safety profile and the description covers when-to-use and header injection. The notable gap is the absence of any input-parameter explanation, which matters given the tool has two optional params.

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 0% and neither of the two input parameters (entities, include_population_stats) is explained anywhere in the description. The description instead documents the output shape, leaving the input parameters undocumented and forcing the agent to infer their meaning.

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 opening sentence states a specific verb and resource: returns live enum values for FilterableField, GroupByField, and MetricField per entity, generated from real workspace data. It is clear and self-contained, but it does not explicitly distinguish itself from the similar sibling get_unique_filter_options, so sibling differentiation is only implied.

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 'Use when' section gives a clear trigger: call when unsure which enum values are valid for a field in the current workspace. It states context well but names no alternative tools (e.g. get_unique_filter_options) or when-not-to-use conditions.

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

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

Annotations declare destructiveHint=true and the description corroborates and enriches it: it states exactly what is written (contacts and relationship paths), the precondition for any result (account must carry a super-connector relationship and the workspace must have buying_committee_regex), how workspace_id/user_id are supplied, and the cost profile of the relevance LLM. It also discloses the multi-record handling expectation, well beyond what the annotations convey.

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?

Purpose and when-to-use are front-loaded, which is good, but the description then re-lists 15 return fields verbatim even though an output schema exists, and restates 'Behavior: destructive' that the annotations already declare. Roughly a third of the text is redundant with structured fields.

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 destructive, side-effecting tool with two loose parameters, the description covers preconditions, side effects, parameter intent, and result handling, and the output schema covers return shape. The only shortfall is that the duplicated return-field list is the kind of detail the schema should own, leaving less room for missing detail such as what happens on partial failure.

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 0%, so the description must carry parameter meaning, and it does: 'Pass the target account ids' for account_ids and an explicit cost-based rule for run_relevance. It stops short of clarifying the expected id format (internal ids vs linkedin ids) or that account_ids may be null/empty.

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 concrete verb chain (find the buying committee a super connector can warm-reach, then create contacts and WORK_OVERLAP relationship paths) and a specific input set (target accounts). It is clearly distinguishable from read-only siblings like search_warm_intro_relationships because it states it materializes data.

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 'Use when' block explicitly covers the on-demand-vs-background-automation tradeoff and gives a clear default for run_relevance ('leave false unless the caller explicitly wants the slower LLM filter'). It does not name the read-only alternative (search_warm_intro_relationships) for agents who only want to inspect without writing, which is the one missing routing cue.

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=false, so the safety profile is largely covered structurally. The description adds no behavioral context beyond a UI drag-and-drop hint: it says nothing about what happens on upload, whether files are persisted, size limits, or auth requirements. Minimal value added.

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, no filler, front-loaded with the action. It is efficient, though the second sentence is targeted at a human dragging files in an interface rather than at an agent, so it does not fully 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 zero parameters and no output schema, the description carries the whole burden of explaining how a call should be made, and it does not. It never says how files are conveyed to the tool or what the result is, leaving an agent with no actionable model of invocation.

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 scores 4. There is nothing for the description to document or to compensate for, and the schema is explicitly closed with additionalProperties=false.

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

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

It names verbs (upload, manage) and a resource (files), so the purpose is broadly identifiable. But 'manage' is a catch-all that does not distinguish this tool from siblings like list_files and read_file, and the second sentence is a UI affordance rather than a scope statement. Vague-but-present, which lands at 3.

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

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

There is no when-to-use guidance and no routing away from the obvious alternatives (list_files, read_file). 'Drop files here to send them to the server' describes a widget interaction, not an agent decision rule. An agent cannot tell from this text when this tool is the right choice.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the 'Behavior: read_only, idempotent' line is partly redundant, but the description adds real value: a truncation signal (truncated), pagination via page/limit, and a hard rule to surface multiple candidates instead of auto-acting. That multi-record discipline is behavior no annotation could convey.

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?

Well front-loaded: purpose, then 'Use when', 'Behavior', and an IMPORTANT action rule. However, the Returns field listing duplicates the existing output schema and the Behavior line repeats the annotations, so a few sentences do little work. Still tight and scannable.

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?

Since an output schema exists, the description needn't document return shape, yet it does; the real gaps are the undocumented pagination/default parameters. Routing, prerequisites, and the multi-candidate handling rule are all present, so it is close to complete for a 10-param read tool.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the full burden. It maps name/regions/industry/company_size conceptually but never explains the industry vs industries vs icp_industries split, page, limit, the country_code='US' default, or icp_industry_categories — leaving roughly half the parameters undocumented anywhere.

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 plus the exact filter dimensions (name, regions, industry, employee band) and names the downstream sibling it feeds (search_people_by_location_and_seniority). An agent can distinguish it from search_accounts_with_filters and the people-search tools 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?

Has an explicit 'Use when' section covering both the routing case (resolve a company name here rather than passing company_name to the people-search tool, to avoid ambiguous-match rejection) and the direct-goal case ('find companies like X', Ohio industrials 200-1000 employees). It also states the required post-call workflow (present multiple candidates and let the user choose).

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/destructiveHint/openWorldHint, so 'Behavior: read_only' is redundant, but the description adds genuinely non-obvious context: workspace_id/user_id are injected from request headers, and a directive about presenting options when multiple records come back rather than acting on all of them. That multi-result handling guidance is behavior the annotations cannot convey.

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

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

Front-loaded with the resource definition and organized into labeled Use when / Behavior / Returns sections, so an agent can scan it fast. Slightly inflated by the redundant 'Behavior: read_only' line (already in annotations) and a returns block that duplicates the output 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?

Despite being a trivial zero-param read, the description covers everything an agent needs: what the vocabulary is, when to call it, that scoping is implicit via headers, the return shape, and how to handle multi-record results. An output schema exists, so the extra returns detail is bonus rather than a crutch.

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

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

Zero parameters, so the schema baseline of 4 applies. The description still adds value by explaining that workspace_id/user_id come from request headers, pre-empting an agent's question about why no scoping parameter exists.

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 categories') and immediately qualifies it as the fixed vocabulary with display labels, even giving example values (Customer, Prospect). This clearly separates it from the similarly named sibling get_workspace_categories and from the bulk_* mutation tools.

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

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

Gives an explicit use case (populate a category picker) and names the three follow-up tools it precedes (BulkSetAccountCategory, BulkAddAccountCategories, BulkRemoveAccountCategories), which is strong routing. It stops short of stating exclusions against the confusingly similar get_workspace_categories sibling or any when-not condition.

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 is covered; the description goes further with the empty/null response behavior and the mandatory rendering contract (no raw JSON, render an editable artifact). It adds real workflow context beyond annotations, though most of the added text is presentation policy rather than tool 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?

The verb and usage guidance are front-loaded and clear, but the definition is bloated: the full field list appears twice (once in the opening sentence, again in the closing 'Also returns pagination info' sentence), and rendering instructions are restated in three places. Roughly a third of the text is repetitive.

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 annotations covering safety and an output schema present, the description need only cover invocation context — and it does: trigger conditions, the empty-document fallback, the generation dependency, and the update_company_profile next step are all present. Nothing an agent needs to call this 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?

The tool takes zero parameters and the description correctly notes workspace_id/user_id are injected from request headers, which is useful context. With no parameters to document, the baseline of 4 applies; there is nothing more to add.

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: 'Retrieve the stored company profile (research document) for the workspace.' The scoping phrase 'for the workspace' plus the enumerated return sections make it unmistakable against siblings like get_user_profile or get_current_workspace, which target different resources.

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 when-to-use ('when the user wants to view or edit the company profile / company research'), names the required follow-up (update_company_profile), and closes off a plausible alternative by explaining GenerateCompanyResearch is not an exposed MCP tool and must be triggered in the app. Error paths and re-invocation conditions are also specified.

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 'Behavior: read_only' is largely redundant. However, the description adds genuinely useful operational context not in annotations: workspace_id and user_id are injected from request headers, so the caller need not supply them. That auth/implicit-parameter disclosure is the value-add here.

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

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

Front-loaded with clear labels ('Use when:', 'Behavior:') and no wasted sentences. Minor blemish: the redundant 'Use when: Use when' stutter, but otherwise tight and well-structured.

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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The definition covers id sourcing and the read-only nature well; the remaining gap is the unexplained optionality of 'id', which leaves a small ambiguity for an agent.

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 0% and the single 'id' param is only typed as string with a null default, so the description must compensate. It does add provenance (the id comes from create_crm_specification's response), which is meaningful, but it never states the id's format or addresses why the param is optional despite being a get-by-id lookup.

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

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

States a specific verb and resource ('Fetch a previously-registered CRM specification by its own id') and implicitly distinguishes itself from the sibling create_crm_specification by scoping to already-registered records. An agent can tell what this does without opening the schema.

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

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

The 'Use when' clause gives an explicit precondition (you already hold a CrmSpecification id from create_crm_specification's response) and the goal (confirm connection_source or check is_deleted). This routes the agent precisely and names the sibling that produces the required 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond that: the returned user_id is the Keycloak 'sub' claim and the same identifier injected as user_id on workspace-scoped tool calls via request context — a non-obvious cross-tool invariant. It does not cover failure modes (e.g., unauthenticated session), which keeps it from 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?

Front-loaded with the core purpose in the first sentence, then when-to-use, then identity semantics. The trailing 'Returns' block partially restates what the output schema already provides, which is slight redundancy, but no sentence is truly 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 zero-param, read-only tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, trigger conditions, and the meaning/linkage of the returned identifier. Return-value detail is arguably redundant given the output schema, so nothing 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?

Zero parameters, so the baseline is 4. The description usefully explains the semantics of the value involved (requestor identity as Keycloak subject), which is more than the empty schema can convey, though there are no parameter names or formats to document.

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 the logged-in/requestor user for this MCP session) and immediately clarifies scope as 'requestor' rather than an arbitrary user, which separates it from siblings like get_user_by_email, get_user_profile, and get_current_workspace. An agent can select 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?

Explicitly enumerates when to call: the user asks 'who am I?', a workflow needs the current user's ID, or before tools that act on behalf of the requestor (intro requests, relationship actions, workspace membership checks). This is a genuine when-to-use list with concrete examples naming downstream sibling tool families.

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, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real context beyond that: it enumerates the returned facets (name, type, description, contact stats) and discloses the failure mode ('an error if none is selected'), which is not derivable from the annotations.

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

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

Front-loaded purpose followed by a usage condition and a Returns block; short and skimmable. The phrase 'workspace you are currently working in' is slightly restated as 'active session workspace', and the Returns block partially overlaps the output schema, but no sentence is 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 simple zero-parameter read tool with full annotation coverage and an existing output schema, the description supplies everything needed: purpose, trigger condition, and the empty-selection error case. Nothing required 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?

The tool takes zero parameters, so the description carries no parameter-documentation burden; the baseline for a 0-param tool is 4. Nothing here 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?

The description opens with a specific verb and resource ('Get information about the workspace you are currently working in'), and the scope word 'current'/'active session workspace' cleanly separates it from search_workspaces and switch_workspace. An agent can identify the tool 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?

It gives an explicit trigger: 'Call this when the user asks which workspace they are in, or wants details about their active workspace.' That is clear when-to-use guidance, though it never names the neighboring alternatives (e.g. search_workspaces, switch_workspace) or states when not to use it.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=false), the description discloses that this is a mandatory automatic follow-up, that it returns editable draft content per type, and how results must be consumed. It does not discuss auth beyond the header-injected workspace_id/user_id note, nor rate/limit behavior, but the added workflow semantics are substantial.

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?

Purpose is front-loaded, but the rendering/persistence instructions are long and largely restated in both the body and the 'Use when' section, which doubles the length. A large fraction of the text is UI-composition guidance rather than tool-selection signal.

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 high-complexity multi-step workflow with an output schema present, the description supplies purpose, sequencing, per-type call pattern, rendering expectations, and follow-up wiring to update_draft and the state-change event. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0% and draft_type has no enum in the schema, yet the description compensates by naming and explaining all three valid values (GHOSTWRITTEN_EMAIL, FORWARDABLE_EMAIL, TEXT) and by saying intro_request_id comes from the request_intro response. It stops short of flagging that neither parameter is schema-required, which is a residual gap.

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

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

States a specific verb and resource ('Fetch the latest AI-generated draft of a specific type for an intro request') and enumerates the three draft types with parenthetical definitions. An agent can distinguish this from update_draft (write) and intro_request_send_state_change_event (submit) purely from the text.

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 when-to-call instructions ('automatically in the same turn immediately after request_intro succeeds — do NOT ask'), an explicit count and argument list for the three calls, and an explicit when-not-to-proceed condition gating the next tool. Alternatives and ordering are fully specified.

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 real value beyond them: the terminal statuses (COMPLETED, PARTIALLY_COMPLETED, FAILED), the 'poll until terminal' loop, the 'do not invent emails' guardrail, and the multi-record handling rule. It stops short of describing pagination semantics beyond noting seconds/nanos.

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?

Purpose is front-loaded and the Use when/Behavior blocks are well structured. However, the lengthy results[] field listing duplicates the output schema (has output schema = true), which is redundant bulk that dilutes the useful guidance.

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 an output schema present, the description is not obligated to enumerate return fields, and its real gaps (job_id format, pagination behavior) are minor. Purpose, trigger, terminal states, and the multi-record caution give an agent everything needed to call it correctly.

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

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

The single job_id parameter has 0% schema description coverage, and the description only hints at its origin ('any flow that returned a job_id') without giving format or expected value. That partial compensation is better than nothing but leaves the one parameter under-specified.

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 (poll) and resource (email extraction job) and describes the returned status/progress. It explicitly ties itself to the sibling submitEmailExtractionJob, so an agent can distinguish it from unrelated job/status tools 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 'Use when' block names the exact trigger (after submitEmailExtractionJob or any flow returning a job_id) and states the alternative that is NOT needed ('no separate results call is needed'). It also instructs polling until terminal, leaving little 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=true, but the description adds real context beyond them: workspace_id/user_id are injected from request headers, the return shape, and a notable multi-record handling rule requiring the agent to present options before acting. This is meaningful guidance the annotations do not carry.

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 and clearly sectioned with 'Use when', 'Behavior', and 'Returns' labels, so an agent can scan it fast. The trailing IMPORTANT block is somewhat verbose but functionally justified.

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 auth injection, usage context, and multi-record behavior, and an output schema exists so return details are already handled. The only gap is the undocumented entity_type parameter, which is minor for a low-complexity read tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that entities are addressed by internal UUID, which adds value for entity_ids, but the entity_type parameter is never mentioned, leaving one of two params undocumented.

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

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

States a specific verb and resource ('Fetch the tags attached to specific entities, keyed by entity id') and clarifies entities are addressed by internal UUID. An agent can distinguish it from list_tags and remove_entity_tags, though no sibling is named 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?

Has an explicit 'Use when' section: 'when you already have entity ids and need their tags', with a concrete example (showing why an account was grouped). No when-not condition or named alternative, so it stops short of a 5.

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

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

The 'Behavior: read_only, idempotent' line merely restates the annotations, earning no credit. However, the IMPORTANT clause about multi-record responses and presenting options to the user before follow-up is genuine behavioral guidance not captured by any structured field. It adds real value beyond annotations, though the annotation echo dilutes it.

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?

Purpose and routing are front-loaded, which is good. But the description then enumerates experiences[] return fields and pagination fields that an output schema already documents, adding bulk without added value. That block should be trimmed.

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

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

For a single-parameter read tool with annotations covering safety and an output schema covering return values, the description is largely complete. The multi-record handling caveat covers the main ambiguity an agent would face. Minor gap: it never states the input is optional.

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 0% for the single parameter, so the description carries the full burden. It specifies that the parameter accepts a bare handle/vanity name OR a full LinkedIn URL, which is materially more than the schema's bare 'string' type. It does not note that the field is optional (default null), leaving a small gap.

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

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

States a specific verb and resource ('Exact lookup of a single person by LinkedIn handle/vanity name') and explicitly distinguishes itself from search_people. An agent can differentiate this from the many search_* siblings 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?

Names the alternative (search_people) and the exact condition that selects this tool ('user gives you a specific LinkedIn profile URL or handle'), then reinforces it with a 'Use when:' clause and an implicit when-not ('not a filtered search'). Nothing is left 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 establish the read-only profile, but the description adds substantial non-obvious behavior: the hard 30-day window that cannot be adjusted, header-injected workspace/user IDs, the caveat that left_provided_company is an unreliable derived signal, the required independent verification before acting, and pagination semantics. This is well beyond what the annotations convey.

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 purpose, then clearly labeled sections (Use when / Behavior / Prerequisites / Next steps), which makes the length navigable. It loses a point for restating 'Behavior: read_only' (already an annotation) and enumerating ~25 return fields despite an output schema being present.

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, paginated list tool this covers everything an agent needs: the result window, scoping behavior, prerequisite caveat, post-call verification, pagination handling, hidden internal fields, and a multi-record presentation rule. With an output schema present, no return-value explanation is owed, and none 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 0%, so the description must carry the load. It does explain account_id thoroughly (plain filter, not an ownership check; omit = workspace-wide) and implies page_number via the pagination next-step. However page_size is never described, leaving one of three parameters fully undocumented.

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?

Names a specific verb+resource (find Power Users who left their import-declared employer) plus the scope and the window ('detected in the last 30 days'). Explicitly distinguishes itself from ownership-scoped siblings ('Not scoped to any notion of account ownership'), so an agent can separate it from the other get_/search_ tools 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?

Gives a clear 'Use when' trigger, explains the account_id omit-vs-pass decision, and closes off an inferred alternative ('no way to widen or shift this window'). It does not name a concrete sibling tool to use instead in adjacent cases (e.g. the ownership-scoped account tools), so it stops just 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 cover read-only/non-destructive, but the description adds non-obvious operational context: workspace_id and user_id are injected from request headers rather than passed as arguments, and actor_id is an internal field that must not be surfaced to users. The 'Behavior: read_only' line merely restates the annotation, but the injection and redaction notes are genuine value-adds.

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

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

Front-loaded with the core purpose and reasonably tight, but it wastes a line on 'Behavior: read_only' which duplicates the annotation, and the closing sentence labels reason/declined_reason/acted_on_behalf_of_referrer/new_holder_id as 'pagination info', which is misleading framing for return fields already covered by the output 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?

An output schema exists, so the description need not enumerate return values, and it correctly focuses on preconditions, implicit header-derived parameters, and the internal-field redaction rule. What is missing is only differential guidance against the sibling state/transition tools, which is a modest gap for a straightforward single-record read.

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 0% with no descriptions on either parameter, so the description has to carry the load and largely does: referrer_id is defined as the workspace member holding the SUPER_CONNECTOR role and referrer_request_id is identified as a UUID. Type/format detail beyond 'UUID' and any error behavior for unknown IDs are absent.

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

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

States a specific verb and resource: fetch a single referrer request by UUID scoped to a given referrer, with a short list of what the payload contains (state, decline reason, reason text, timestamps). It is clear what the tool does, though it never explicitly contrasts itself with the closely-named siblings referrer_request_get_current_state or referrer_request_get_state_machine_transitions.

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 'Use when' sentence gives concrete preconditions (you hold referrer_request_id and referrer_id) and a motivating scenario (need status/decline reason/timestamps before SendStateChangeEvent). It lacks a when-not-to-use clause or a pointer to the narrower state-only siblings, so the boundary against alternatives remains implicit.

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 usefully adds that workspace_id/user_id are injected from request headers (the agent cannot pass them) and that the full markdown_body is returned. It does not explain what scope/scope_id resolve to when omitted. Note idempotentHint=false on a read, which the description neither confirms nor contradicts.

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 purpose and usage lines are front-loaded and efficient, but the trailing dump of ~25 return fields duplicates the existing output schema and pads the definition. The 'Behavior: read_only' line also restates the readOnlyHint annotation.

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?

An output schema exists, so the long return-field list is unnecessary, and the real gap is the undocumented scope/scope_id semantics. For a low-complexity 2-param read tool the description is largely sufficient, but the parameter ambiguity keeps it from being fully complete.

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

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

Schema coverage is 0% and neither param has a description, so the description must carry the load. It implies scope selects USER vs WORKSPACE and scope_id is the identifying value, but it never states valid values, format, or what happens when both are null, leaving the two params only partially clarified.

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 ('Load') and resource ('the single MEMORY document'), scoped to USER or WORKSPACE, and notes it returns the full markdown_body. It does not explicitly name the siblings upsert_scoped_memory or delete_scoped_memory, so an agent distinguishes it by verb semantics rather than explicit routing.

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 'Use when' clause gives a concrete workflow: retrieve the existing scoped memory document before merging an observation into it (read-before-write). It gives clear context but never states exclusions or names the write/delete alternatives it should be preferred over.

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/idempotent/destructive=false, and the description redundantly restates read_only/idempotent. What it genuinely adds is auth context (workspace_id/user_id injected from request headers) and the DEPRECATED status, which annotations do not convey.

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 critical DEPRECATED notice is buried mid-description rather than front-loaded, and 'Behavior: read_only, idempotent' merely duplicates the annotations. It also enumerates return fields despite an output schema existing, adding noise.

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?

An output schema exists so return values needn't be explained, yet the description lists them anyway. Useful context on deprecation and header injection is present, but the sole input parameter is left undocumented, leaving a real gap for a metadata-fetch 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?

One parameter (keycloak_user_id) with 0% schema description coverage, and the description never explains it. It discusses injected header fields (workspace_id/user_id) instead, which actually raises confusion rather than clarifying the declared keycloak_user_id parameter.

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

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

States a specific verb (fetch) and resource (super connector metadata) with concrete scope: how/why it was provisioned, including roles, qualifying company, and evidence types. However it does not distinguish itself from the sibling get_super_connector_metadata_bulk, leaving an agent to guess which of the two to pick.

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?

Provides a clear 'Use when' clause tied to assessing relationship closeness, plus a high-value DEPRECATED flag. It gives no when-not guidance and never names the bulk alternative as the preferred route, so the routing decision between the two metadata tools is left 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 declare readOnly/idempotent, but the description adds material context beyond them: workspace_id/user_id are injected from request headers (no auth parameter needed), the returned entries[] shape, and a behavioral caution to present multiple records to the user rather than acting on all of them automatically.

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

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

Front-loaded with the purpose, then organized into Use when / Behavior / Returns / IMPORTANT sections that are easy to scan. Slightly long and partially duplicates the output-schema field list, but every section 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?

Covers purpose, usage, header injection, return shape, and a multi-record safety caveat. Since an output schema exists, re-listing entries[] fields is redundant rather than harmful, but the description is complete enough for correct invocation.

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 0% and the single parameter has no description, so the description must carry the load. It does clarify the parameter's semantics ('1..N super connector ids in a single call'), though it does not state that the field is optional with a null default.

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

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

States a specific verb and resource (fetch provisioning metadata for super connectors) plus exactly what is returned: roles, qualifying company, evidence, relevance verdict with score and band. It is clearly distinguishable from the sibling get_super_connector_metadata by the explicit bulk 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?

Provides an explicit 'Use when' clause, an alternative rule ('always prefer this over calling repeatedly per id'), and a fallback path ('fall back to notes for connectors that have not been scored yet'). Also states it covers both single-id and multi-id lookups, removing the main routing ambiguity.

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 genuinely new context: 'workspace_id / user_id are injected from request headers' (no need to supply them) and a mandatory post-call behavior ('If the response contains more than one record, always present the options ... ask them to choose'). 'Behavior: read_only' merely restates the annotation, and response format is duplicated rather than adding nuance, which keeps this 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?

Front-loads well with purpose and a 'Use when' block, but roughly half the text is a 14-times-repeated 'Returns X[] with fields: value label count' listing that duplicates the existing output schema verbatim. That bulk crowds out the genuinely load-bearing content (the reference_id semantics) and provides no decision-relevant 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?

Since an output schema exists, the return-value section is unnecessary and the space should have gone to the three parameters: the description never explains what 'reference_id' should contain or how it selects the scope, and 'search' is entirely undocumented in both schema and description. For a zero-required-parameter scoping tool, that leaves the agent guessing at the most important input.

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?

Coverage is only 33% and the schema carries a very rich description for 'filters' but nothing for 'search' or 'reference_id'. The description clarifies the intent of filters ('Pass any already-active filters to narrow the returned option lists dynamically') and says the scope is an account, contact, or super connector, but never states how to pass that scope (which parameter, UUID vs. id) or what 'search' does — meaningful gaps remain.

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

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

States a specific verb and resource ('Fetch available filter option values ... for warm intro paths') and enumerates exactly which option families are returned. It also names the sibling it is not ('Do not use this to retrieve relationship paths — use SearchWarmIntroRelationships'), so an agent can separate the two 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?

Has an explicit 'Use when' block that ties usage to a concrete situation (before/alongside SearchWarmIntroRelationships when showing the user available filter values) and an explicit exclusion routing relationship-path retrieval to the sibling. It additionally explains that already-active filters should be passed to narrow the option lists, which is a usage rule, not just a schema fact.

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

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

Annotations already declare readOnlyHint=true, so the 'Behavior: read_only' line adds nothing. The description does add useful context that the result resolves identity before workspace member updates, but the closing claim about 'pagination info' for a single-user lookup is confusing and arguably incorrect behavior disclosure.

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 'Use when:' guidance is front-loaded and valuable, but the description is padded with a self-referential restatement ('Use get_user_by_email to check if someone already exists') and a trailing sentence about pagination fields that does not belong in a single-entity lookup.

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 an output schema, the description covers purpose, routing, and identity resolution adequately; return-value detail is legitimately delegated to the output schema. Only the misleading pagination sentence detracts.

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 0% and the single 'email' parameter is undocumented in the schema, but the description effectively supplies the semantic ('look up ... by email address'). It adds no format, case-sensitivity, or required/optional guidance, so it compensates only partially.

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 ('Look up a platform user by email address') and immediately names the returned identity fields (Keycloak ID, name, LinkedIn ID). An agent can distinguish this lookup-by-email tool from get_current_user, get_user_profile, and search_workspace_members 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?

Explicit when-to-use with a named alternative and a fallback sequence: 'If email is unknown during an update, prefer search_workspace_members to find existing members, confirm identity with the user, then call create_workspace_member with the resolved email.' This is exactly the routing information an agent needs.

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/destructiveHint, so safety is covered; the description adds genuinely new behavioral context (read-only nature restated, dependency on GenerateUserResearch, pagination-ish return fields, mandatory same-turn rendering). The heavy 'IMPORTANT — rendering instructions' is domain-specific but does disclose post-call behavior beyond structured fields.

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?

Purpose is front-loaded and readable, but the rendering instruction ('do NOT dump raw JSON...') is repeated three times across the description, 'Use when' block, and 'Next steps', and the returned-field list duplicates the output schema. Length is not matched by unique 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 read-only fetch with an output schema and annotation coverage, the definition supplies the key missing pieces: read-only behavior, ordering dependency on GenerateUserResearch, and the required follow-on call. Return-value enumeration is redundant given the output schema, and parameter format is left unspecified, keeping it just short of full.

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 0%, so the description must carry the load. It only notes that 'workspace_id / user_id are injected from request headers', which adds meaning for injection but leaves the single user_id parameter's type/format/requiredness unexplained (the schema lists it as an optional string). Baseline is adjusted down since the gap isn't fully compensated.

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 ('Retrieve the stored person profile (research document) for a user in the workspace') and clarifies the returned structure. This distinguishes it from siblings like get_company_profile and get_current_user, so an agent can select 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?

Gives explicit when-to-use ('view or edit the researched role for a person in the workspace') plus a documented alternative path ('if no document exists yet, trigger GenerateUserResearch first, then call get_user_profile again'). The next-steps block names update_user_profile as the follow-on action, so routing is unambiguous.

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, but the description adds substantial non-structured behavior: filter semantics for relationship_type/is_deleted, the id-as-value / label-as-display mapping, and a strong interaction rule that multiple results must be presented to the user for selection before any follow-up action. This goes well beyond the annotation's safety profile.

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?

Purpose is front-loaded and useful, but the description then enumerates the full return field list (id, name, value, label, description, definition, is_tracked, parent_id, type, logo, relationship_type, order, is_deleted, meta, created_at, category_features) even though an output schema exists. That enumeration is redundant and inflates length, though the surrounding usage guidance 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 no-param, output-schema-backed read tool with rich annotations, the description is largely complete and adds filtering and interaction guidance. The only gap is that it duplicates return-field documentation already covered by the output schema, slightly diluting rather than completing the definition.

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

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

Zero input parameters, so the baseline of 4 applies per the rubric. The description instead documents how returned fields are consumed (id as option value, label for display), which compensates for the empty input schema but is not strictly required.

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

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

States a specific verb+resource ('List all categories configured in the current workspace') and immediately distinguishes itself from similar-sounding siblings like get_account_categories and list_tags by scoping the resource to workspace categories. An agent can identify the tool's role 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?

Explicitly states when to call it (before rendering the add–Super Connector form, populating a Category dropdown), when NOT to ('Do NOT use with create_workspace_member for Super Connectors'), and a third use case (filtering FILTER_FIELD_CATEGORY in search_warm_intro_relationships). Names concrete downstream tools and the exact filter conditions.

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 read-only, idempotency, and destructive/open-world flags, so the 'Behavior: read_only' line is redundant. What the description does add beyond structured data is that workspace_id/user_id are injected from request headers and that mixing partial keys returns INVALID_ARGUMENT / 'requester_id is required' — genuinely useful error and context disclosure.

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 same mode rules are stated three times — in the opening 'TWO lookup modes' block, again under 'Use when', and again under 'Prerequisites (check before calling this tool)'. The redundancy bloats the definition well past what is needed and buries the routing rule in 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?

An output schema exists, so return values need not be described, and the otherwise-undocumented parameters are fully explained. For a 3-param, zero-required lookup tool, everything needed to call it correctly and to handle the invalid-input case is present.

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 0%, so the description carries the full burden, and it does: it defines the two valid key combinations, marks each mode's required fields, and enumerates the invalid partial-key shapes. This is far more than the bare anyOf string schema provides.

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

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

The first sentence names a specific verb and resource ('Get current_state for an intro request'), and the description explicitly distinguishes this from the sibling search_intro_request for full details. An agent can tell what this tool returns and when a sibling is the better pick 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?

It spells out two mutually exclusive lookup modes (intro_request_id only, or target_id + requester_id), names the invalid combinations, and routes the agent to search_intro_request when intro_request_id is known. This is explicit when/when-not/alternative guidance rather than implied usage.

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 is covered. The description adds genuinely useful context beyond annotations: 'No input — returns the full graph in one call,' the header injection note (workspace_id/user_id), the IMPORTANT rule to present multiple options rather than auto-acting, and actor-role constraints. The actor/auth detail and multi-record caution are real behavioral value.

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?

Well-structured with front-loaded purpose and clear labeled sections (Use when, Behavior, Next steps, Returns). It is somewhat long and repeats the current_state pairing twice, and the per-field 'Returns' detail partially duplicates the output schema, but nothing is misleading and the sections are skimmable.

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, zero-param tool with an existing output schema, the description is more than sufficient: it explains the edge semantics, the actor model, the follow-up flow, and the guardrail on multiple results. Nothing an agent needs to invoke or reason about this tool 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?

This is a zero-parameter tool, so the baseline is 4. The description correctly states 'No input — returns the full graph in one call,' which matches the empty schema and removes any ambiguity about required arguments.

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: 'Return the complete intro request state machine transition graph,' and clarifies the row semantics (directed edge source_state → target_state plus event/actor). It is clearly distinguishable from the sibling referrer_request_get_state_machine_transitions and from intro_request_get_current_state by naming both the resource scope and the pairing relationship.

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?

Explicit 'Use when:' block gives the lifecycle-understanding context and a concrete trigger ('Call before intro_request_send_state_change_event whenever you are unsure what transitions are legal'). It names alternatives and the exact sequencing: current_state first, then filter transitions by source_state and allowed_actor.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces rather than contradicts that ('Behavior: destructive'). Beyond annotations it adds genuine value: the returned fields (previous_state, current_state, transition occurred), rejection of invalid events, and that workspace_id/user_id are injected from headers. Only minor repetition of the annotation's destructive flag keeps it from 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?

The content is front-loaded and header-organized, but the lookup constraint is stated three times (the Lookup paragraph, the first prerequisite's Verify line, and again in that Verify wording), and the numbered workflow duplicates the prerequisites section. Every sentence is informative, but the redundancy costs it conciseness.

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

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

For a destructive, non-idempotent state-machine tool with five loosely-typed parameters, the description covers prerequisites, valid-edge confirmation via intro_request_get_state_machine_transitions, actor matching, and fallback lookup. An output schema exists, and the description still summarizes the return shape, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is only 20%, so the description must carry the load, and it does for the identity parameters: intro_request_id alone is preferred, or target_id + requester_id together, never intro_request_id + target_id without requester_id. The event parameter is only pointed at intro_request_get_state_machine_transitions rather than explained, so event value semantics remain schema-dependent.

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+resource framing ('Fire a state machine event to move an intro request from its current state to a new state') and immediately distinguishes itself from the sibling read tools by describing the transition semantics. An agent can tell it apart from intro_request_get_current_state and intro_request_get_state_machine_transitions without opening any schema.

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

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

It explicitly lists the situations ('advance, submit, cancel, withdraw, or discard an intro request'), provides a numbered workflow for the ambiguous case, and warns 'Do not guess events — invalid events are rejected.' It also names the alternative lookup paths and the exact invalid argument combination to avoid.

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, idempotent, non-destructive, and closed-world behavior, so the description is not burdened with safety disclosure. It adds that results cover 'all' files and include 'metadata', but does not mention pagination, sorting, or auth requirements; against rich annotations this is 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?

One sentence, front-loaded with the verb and resource, no filler. Every word earns its place for a simple listing operation.

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

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

With no parameters, rich annotations, and a separate output schema, the description only needs to state the operation, which it does. It could be improved by noting pagination or ordering, but the output schema likely covers return values.

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?

There are zero parameters, and schema coverage is 100%; the description has no parameters to explain. Baseline for zero params is 4.

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

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

States a specific verb (List) and resource (uploaded files), and adds the scope 'all' plus mention of metadata. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like read_file or file_manager.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named. The agent must infer from the phrase 'List all uploaded files' that this is the listing tool, with no help on when read_file or file_manager would be preferred.

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/idempotent/non-destructive/openWorld=false, but the description adds genuine context: 'does not scrape LinkedIn' (reads cached history), the internal-fields-do-not-display warning, and the multi-record disambiguation rule. These are non-obvious operational constraints that the annotations do not convey.

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?

Purpose is front-loaded and header-style sections help scanning, but there is redundancy: 'Read-only — does not scrape LinkedIn' overlaps the 'Behavior: read_only, idempotent' line and the readOnlyHint annotation, and the 'Returns activities[] with fields' block restates an output schema that already exists.

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 4-param read tool with an output schema, the description covers purpose, invocation constraints, param formats, hidden internal fields, and multi-result handling. It is essentially complete; only pagination semantics (beyond listing page/page_size as internal) and row-count expectations are left implicit.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it specifies the mutual-exclusivity constraint (exactly one of keycloak_user_id OR linkedin_handle), names the required start_date/end_date, and gives the yyyy-MM-dd format. All four parameters are meaningfully documented where the schema is silent.

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 stored LinkedIn engagement for a tracked person) with explicit scope (date range, stored history). It cleanly distinguishes itself from siblings like get_person_by_linkedin_handle and search_people_in_companies, which fetch identities or search people rather than engagement history.

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?

Provides an explicit 'Use when' clause tying the tool to a user/trigger asking about commented-on or reacted-to posts, plus a parameter preference ('Prefer linkedin_handle when known'). It lacks a when-not/alternative comparison against a sibling, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them: headers inject workspace_id/user_id, and it introduces a non-obvious multi-record rule requiring the agent to present choices and await user selection before acting.

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 purpose followed by labeled sections (Use when / Behavior / Returns / IMPORTANT). Slightly verbose – the Returns block restates fields already present in the output schema – but structurally clean and easy to scan.

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

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

Given an existing output schema, return values need not be explained; the description still covers purpose, usage, injected auth context, and a critical interaction constraint. Adequate and mostly complete, with only the entity_type value space left undefined.

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 0%, so the description must compensate. It maps search_text to a 'name substring' narrowing, which is helpful, but entity_type is only described as 'a given entity type' with no valid values, format, or default guidance for the two parameters.

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

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

Specific verb (List) plus resource (customer-defined tags) plus scope (this workspace, given entity type, optional name substring). It cleanly distinguishes itself from siblings like create_tag, get_entity_tags, and assign_tags_by_name 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?

Explicit when-to-use: discover which tags exist and their ids before attaching or filtering by tags. Clear context, but no explicit when-not or named alternatives (e.g., get_entity_tags for read on a specific entity).

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 the safe read profile, but the description adds substantial context beyond them: the OWNER/ADMIN/SUPER_CONNECTOR_ADMIN gate that controls whether WEBHOOK templates appear, the failure inference when they are absent, the fact that workspace_id/user_id are header-injected, and the instruction to surface multiple results to the user rather than act. This is far more than the annotations convey.

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?

Well front-loaded with clear 'Use when' and 'Behavior' sections, and the IMPORTANT caveat is called out. It loses a point for redundancy: the returned fields are enumerated in prose at the top and then listed again with descriptions, which is duplicated content.

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

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

Despite an output schema already existing, the description covers everything an agent needs: permission gating, what to do when WEBHOOK templates are missing, what to copy before calling createWorkflowTrigger, and the multi-result handling rule. No gaps for a zero-param read tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead documents the semantics of the returned fields (template_id to copy verbatim, trigger_kind passed through to createWorkflowTrigger, metadata.supported_events required for WEBHOOK), adding downstream meaning, though that overlaps with the output 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 ('List admin-managed trigger templates for the workspace') and immediately names what it returns (id, name, trigger_kind, metadata). It explicitly distinguishes itself from the sibling listWorkflowTriggers ('that lists live activations / catalog rows') and from createWorkflowTrigger, so an agent can route 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?

A dedicated 'Use when' block gives the trigger conditions (browsing/picking a template, or missing a workflow_trigger_template_context seed), the sequencing ('Call before createWorkflowTrigger'), the preference rule ('Prefer this over inventing WEBHOOK event slugs'), and the exclusion ('Not a substitute for listWorkflowTriggers'). Both when-to-use and when-not-to-use are 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 and destructiveHint=false, so 'Behavior: read_only' is redundant. However the description adds real behavioral context the annotations do not: the empty-id-means-unactivated-template semantics, the config-UUID interpretation, and the IMPORTANT rule to present options and not auto-act when multiple records return.

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?

Well front-loaded with Use when/Behavior headers, but the tool has an output schema, so the long enumerated dump of ~30 return fields (name, description, enabled, last_run_at, ...) is pure redundancy and bloats the definition without adding call-time value.

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

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

Annotations and an output schema carry the safety profile and return shape, and the description covers usage and follow-up routing thoroughly. The only remaining gap is the undefined set of acceptable status values, which is minor for a filter with a null default.

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 0% and the single 'status' param has no description or enum. The description partially compensates by specifying that 'status' filters on lifecycle status, but it never enumerates the allowed status values, so the agent still cannot pick a valid value from the definition.

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 and scope: 'List a recipient's workflow triggers (catalog-based and agent-created)'. Combined with the sibling routing in the 'Use when' block (update_workflow_trigger, create_workflow_trigger), an agent can distinguish this list tool from its write siblings 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?

Explicit when-to-use ('before creating a new trigger to avoid duplicates, or when the user refers to that reminder'), plus named alternatives with selecting conditions: route to update_workflow_trigger with the row's id, and to create_workflow_trigger when id is empty. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false) the description discloses that the action is irreversible from chat, that the retired member is removed, the dry_run-then-confirm protocol, and the MERGE_OUTCOME_REFUSED handling with refusal_reason. It also sets an output-copy contract (talk about people by name, hide ids/enum strings), which is behavioral context no annotation carries.

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

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

Front-loaded with purpose and consequence before the procedural steps, and organized into clear blocks (workflow, Use when, Behavior, Prerequisites). It is long and the safety rules are restated in both prose and the prerequisites block, but for an irreversible merge the redundancy is largely load-bearing; only mild trimming is possible.

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?

Complete for a destructive, irreversible operation: it covers the two-phase call flow, both id prerequisites with verification, the confirmation gate, refusal outcomes, and the user-facing copy rules. An output schema exists and the description still names the returned fields, so nothing an agent needs to call this safely 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 0%, so the description must carry all four parameters, and it does: it defines keeper_user_id semantics ('the member to keep, usually the one with more data or a login') versus retired_user_id ('must not have a login'), and specifies the dry_run and confirm values and the required pairing across the two calls. It fully compensates for the undocumented schema.

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

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

States a specific verb+resource ('Merge two workspace members who are the same person') and immediately scopes it with the real-world case ('e.g. a Super Connector added twice'). It is clearly distinguishable from siblings like create_workspace_member, update_workspace_member and search_workspace_members, and describes the exact data consequence (relationships, connections, categories, tags, roles move to the keeper).

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 when-to-use ('only when an admin asks to merge, combine or de-duplicate two members'), when-not ('never merge on your own initiative'), and the alternative/upstream tool to use first ('Get both user ids from search_workspace_members'). A numbered prerequisite block repeats the conditions with verification steps, so the agent knows exactly how to reach a callable state.

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/idempotentHint/destructiveHint, so the repeated 'read_only, idempotent' adds nothing; however the description adds real behavioral context with the funnel progression stages and the rule about presenting multiple records to the user before acting. It does not cover pagination/limit behavior, 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?

Front-loaded with the core action, then cleanly segmented into Use when / Behavior / Returns / IMPORTANT. Slightly long, and the Returns field enumeration largely duplicates the output schema rather than earning 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?

An output schema exists, so the description need not explain return values (though it does), and annotations carry the safety profile. Intent, usage, funnel semantics and multi-result handling are all covered; only the undocumented non-filter parameters leave a 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?

18 parameters at 0% schema description coverage, and the description compensates only partially: it names filter dimensions (region, seniority, title keywords, company set) and points to an equivalent sibling schema, but page, page_size, preview, per_company_limit, name_anchor, workspace_id and exclusion params are never explained. Most parameter semantics remain undocumented in both schema and description.

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

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

States a specific verb and resource ('preview how many companies and people match a SearchPeopleRequest at each funnel stage') and explicitly contrasts it with the final search. The funnel-stage enumeration makes the tool's function unmistakable and distinguishes it from sibling search_people_by_location_and_seniority.

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?

Has an explicit 'Use when' clause naming the interactive-refinement context and an explicit exclusion ('Do not use as a substitute for the final search_people_by_location_and_seniority call'). The alternative and the condition that selects it are both named.

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, and the description reinforces with 'Behavior: read_only'. Beyond the annotations it adds genuinely new context: workspace_id/user_id are injected from request headers (so the agent needn't supply them) and a behavioral rule that multi-record responses must be presented to the user before follow-up action. The idempotentHint=false is not discussed, but the added operational guidance is substantial.

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

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

Front-loaded with the purpose sentence, then cleanly sectioned into Use when / Behavior / Returns / IMPORTANT. Every block carries usable information. It is slightly verbose in restating read-only and listing return fields, but nothing is wasted in a way that hurts selection.

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 lookup tool with an output schema (so return detail is optional) and annotations covering safety, the description supplies purpose, usage trigger, header-injection behavior, and the multi-result handling caveat. It omits how the six filter parameters combine (AND/OR, which take precedence) and pagination/limit behavior, which are the main remaining gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden. It names most parameters (slug, query, family, tags, scope) and gives concrete family values (SKILL, MEMORY), which is real added meaning. It never mentions 'limit' and gives no syntax or format guidance for slug/query (which are typed as open objects in the schema), leaving the semantics partially covered.

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 (Query) and resource (agent content) plus the filter facets used to locate it (slug, natural-language query, family, tags, scope). It names the two content families SKILL and MEMORY, making the scope concrete. It does not, however, differentiate itself from the memory siblings (get_scoped_memory, upsert_scoped_memory), which an agent would need to route correctly.

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

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

The 'Use when' clause gives real context: loading a skill by slug on demand, or searching for content not already injected in the runtime bundle. That is a clear usage trigger, not a tautology. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it falls just short of a 5.

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