Follow Up Boss MCP by usefulapi

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

The only annotation is destructiveHint=true, so the description carries most of the behavioral burden. It adds the 'contact's timeline' placement, which is useful, but says nothing about permissions, whether the note can later be edited/deleted, or why the operation is flagged destructive — surprising for an append-style note.

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

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

Two short sentences with the action front-loaded and no filler. The endpoint string is marginally useful for API mapping but adds little for an agent deciding whether to call the tool.

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

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

For a mutation tool with no output schema and fully documented parameters, the essentials are present. However, the description omits authentication/scope requirements and any side effects, leaving behavioral gaps that annotations alone do not fill.

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

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

Schema description coverage is 100%, with all four parameters (personId, body, subject, isHtml) documented inline, so the baseline is 3. The description adds no additional syntax, formatting, or length-constraint detail beyond the schema.

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

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

States a specific verb and resource with scope: 'Add a note to a contact's timeline,' plus the underlying endpoint. It is clearly distinguishable from list/get/update siblings, though it names no alternatives explicitly to sharpen the boundary.

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

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

There is no when-to-use guidance, no prerequisites (e.g., person must exist), and no mention of alternatives such as fub_log_call or fub_send_lead_event for related timeline entries. The agent must infer usage from the name alone.

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

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

readOnlyHint already declares a safe read. Beyond that, the description discloses a non-obvious behavioral trait: it sees contacts the user cannot otherwise see, and returns assignment information. This is meaningful context the annotations don't 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?

Three tight sentences; the core behavior and the usage trigger are front-loaded with no wasted wording.

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 with no output schema, the description conveys the key return concept (existence plus assignment). It could say more about the response shape (e.g. whether multiple matches are returned), but it is essentially complete for calling the tool.

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

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

Schema description coverage is 100%, so both email and phone are fully documented in the schema. The description adds no format or syntax detail beyond restating the email-or-phone lookup, so baseline 3 applies.

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

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

States a specific verb (check) and resource (contact/email/phone) and clarifies scope: it searches the entire account, including records this user cannot see. This implicitly distinguishes it from search/get siblings, though it never names them 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?

'Use before adding a lead' gives a clear trigger context. It doesn't spell out exclusions or point to alternatives like fub_search_people or fub_get_person, but the when-to-use guidance is concrete.

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

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

Annotations only declare destructiveHint=true, so the description carries the rest of the behavioral burden. It discloses a genuinely non-obvious consequence — a deal with no users is invisible to agents — which the schema and annotations never state. It does not cover permissions or side effects of creating against existing records.

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

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

Three short sentences, front-loaded with the core action, then the prerequisite and the critical omission warning. Every sentence carries 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 15-parameter mutation tool with no output schema, the description covers the two required inputs and one critical behavioral trap but leaves the bulk of optional parameters (pricing, commissions, closing dates) unexplained. Adequate to call the tool for a minimal deal, incomplete for a fully specified one.

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 47% across 15 parameters, so the description must compensate and only partly does: it clarifies where stageId comes from and warns about userIds. The other 13 parameters, including all the commission and date fields, get no explanation beyond sparse schema text.

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

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

States a specific verb and resource ('Create a deal in a pipeline stage') and adds the scope detail that the stage must come from a pipeline. It does not explicitly distinguish itself from fub_update_deal or fub_list_deals, but the create verb is unambiguous.

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

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

Gives actionable prerequisites: stage ids must be obtained from fub_list_pipelines, and userIds should be included or the deal becomes invisible. It lacks an explicit when-not condition or a direct comparison to fub_update_deal, 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 only supply destructiveHint=true, so the description carries most of the burden. It adds a genuine behavioral constraint (the assignee one-of requirement), but omits auth/permission needs, side effects such as notifications to the assignee, and what is returned on success.

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; the assignment requirement is front-loaded right after the core purpose. Every clause carries information.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the most important constraint but not the response shape or failure modes. Also pthe allowed task 'type' values and due-date formats are left entirely to the schema.

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

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

Schema description coverage is 78%, so the schema already documents most fields (name, type enum, dueDate, dueDateTime, remindSecondsBefore). The description adds value by stating the cross-field constraint that assignedUserId or assignedTo is required — a relationship absent from the schema's required list.

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

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

States a specific verb and resource ('Create a task'), names the target entity it attaches to ('on a contact'), and repeats the underlying API operation (POST /v1/tasks). This is immediately distinguishable from fub_update_task and fub_list_tasks without inspecting schemas.

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

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

The description supplies one real usage rule: an assignee must be given via assignedUserId or assignedTo. It says nothing about when to prefer this over alternatives, prerequisites (e.g. the person must already exist), or when creation would fail.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds information annotations cannot: the call is 'cheap' (cost/latency profile) and serves as an API-key validity check, while also naming what is returned.

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

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

Three short sentences, none wasted: purpose first, practical use case second, API endpoint reference last. Well front-loaded 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?

With no output schema, the description carries the burden of describing the return payload and does so at a useful level (account id/domain/owner, authenticated user). It stops short of describing failure behavior on an invalid key, which would be the final piece for a credential-check 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 by rule. The description correctly adds nothing about inputs and instead describes outputs, which is the right emphasis for a no-arg tool.

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

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

States a specific verb+resource ('who the credential belongs to') and enumerates the returned entities: account id, domain, owner, authenticated user. This is unmistakably distinct from all siblings, which operate on people, deals, tasks, and notes.

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 — 'a cheap way to confirm the API key works' — which tells the agent when to reach for this tool (credential validation/diagnosis). It doesn't spell out exclusions or a named alternative, but for a zero-argument identity probe none is really needed.

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

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

readOnlyHint=true already establishes the safe read profile, so the description needn't restate it. Beyond that it adds little behavior: no mention of missing-id errors, response size, or rate limits; the "allFields" tip duplicates the schema rather than disclosing new behavior.

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

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

Two short, front-loaded sentences; the core action leads and the endpoint mapping trails. The endpoint line is mildly redundant for invocation purposes but costs almost nothing.

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

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

For a two-parameter, annotation-covered read tool with no output schema, this covers the essentials: what it returns conceptually (contact plus custom fields when requested) and how to widen the field set. Only the absence of any return-shape or error hint keeps it from 5.

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

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

Schema coverage is 100%, so both `id` and `fields` are already documented in the input schema. The description's fields="allFields" note merely restates the schema's own enum-like guidance, so it earns the baseline rather than more.

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 one contact by id") plus the underlying REST endpoint, which lets an agent separate it from list/search siblings such as fub_search_people and fub_list_* tools. It never explicitly names a sibling, so it stops short of a 5.

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

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

Usage is only implied: "by id" signals this is the lookup for when you already know the identifier, versus fub_search_people for discovery. There is no explicit when-to-use/when-not statement or named alternative, which is the minimum viable level.

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 readOnlyHint, and the description goes well beyond that: it discloses that numbers are approximate versus the in-app report, that coverage is limited to what the API key can see, and that a single call can issue at most 100 FUB requests. Those are real behavioral constraints an agent cannot infer from 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 in the first clause, followed by use case, caveats and limits; every sentence carries actionable content. The trailing API endpoint listing (GET /v1/people totals, GET /v1/users) is implementation detail that adds minor clutter for an agent deciding how to call the tool.

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

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

With no output schema and a 5-parameter tool, the description explains what is counted (per-agent source counts, conversion to closed stages, per-lender counts) and the visibility/approximation caveats. It stops short of indicating the shape or grouping of the returned result, which is the one remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning by tying the parameters to the underlying request budget ('one per count') and clarifying that lender counting is a separate dimension controlled by includeLenders. It does not restate syntax, but it explains parameter intent beyond the schema text.

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

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

States a specific verb and resource set: counts leads by lead source per assigned agent, conversion to closed stages, and leads per lender user. It explicitly distinguishes itself from the sibling fub_search_people as the counting alternative, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use rule ('Use it to count instead of paging through fub_search_people') and names the alternative it replaces. It also adds a pre-condition on credentials ('use an owner, admin or broker key for the whole account'), which is exactly the kind of guidance that prevents a wrong call.

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

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

The readOnlyHint annotation already establishes the safety profile, so the description's marginal job is to add context. It does: it describes the shape of each returned record (invitees, type, outcome) and maps the operation to the backend endpoint (GET /v1/appointments). No output schema exists, so this return-content hint is genuinely additive, though pagination behavior is only implied via the schema.

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

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

Two compact sentences that front-load the resource and its contents, then the filtering options, with no filler. The endpoint reference is terse and appended last rather than interrupting the core 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?

For a six-parameter, zero-required list tool with no output schema, the description covers the resource, its returned fields, and the valid filter combinations. Remaining gaps (pagination mechanics, default page size) are carried by the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so every parameter (start, end, limit, offset, userId, personId) is already documented in the schema. The description only restates the start+end coupling and the person/user filtering that the schema already explains, so baseline 3 applies.

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

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

States a specific verb+resource ('Calendar appointments') and even summarizes the record contents (invitees, type, outcome), so the agent knows exactly what is returned. It does not explicitly name or contrast against close siblings like fub_list_events or fub_list_calls, which leaves some disambiguation to inference.

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

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

Gives concrete usage context: filter by person, by user, or by a start+end window, with the explicit constraint that start and end are 'both required together'. There are no when-not conditions or named alternatives, but the calling contexts are clearly laid 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?

readOnlyHint=true already establishes the safe-read profile, so the description's burden is lighter. It adds useful context about the returned record content (outcome, direction, duration), but says nothing about pagination limits, ordering, default page size, or auth scope beyond what the schema already carries.

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

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

Three short clauses, front-loaded with the resource, then filters, then the API anchor. Nothing is padded, though the trailing "FUB: GET /v1/calls" is metadata rather than agent 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 no output schema, the description partially compensates by naming the fields a call carries, and all six parameters are covered by the schema. It stops short of describing paging behavior or result ordering, but nothing essential is missing for a read-only list call.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema with defaults, ranges and the deep-paging hint. The description's "filter by person or number" merely summarizes the personId/phone/toNumber/fromNumber set without adding format or semantics beyond the schema. Baseline 3 applies.

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

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

Names the resource concretely (logged phone calls) and characterizes the record shape (outcome, direction, duration), and the API route anchors it. The verb is only implied by the name/title rather than stated in the description, but an agent can still tell this is a read/list tool distinct from the sibling fub_log_call.

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?

"Filter by person or number" gives implied usage context for the filter parameters, but there is no explicit when-to-use statement, no exclusion of the write-side sibling fub_log_call, and no guidance on when to prefer this over fub_search_people or fub_get_person for call history.

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

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

readOnlyHint already declares the safe read profile, so the description's burden is lower. It adds real value by disclosing the returned field shape and the customXxx API-name convention, plus how the result is consumed. It stops short of describing pagination or ordering behavior, but the core behavior is well conveyed.

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

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

Two tight sentences with the resource description front-loaded and a compact endpoint reference at the end. Every clause carries information; nothing is filler.

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

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

For a simple, read-only list tool with full schema coverage and no output schema, the description is nearly complete: it covers what is listed, the key naming convention, and how to use a result. Only the return ordering/paging narrative is absent, which is minor here.

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

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

Schema description coverage is 100%, with label, limit, and offset all documented in the schema itself, so the baseline is 3. The description adds nothing about parameter formats or constraints beyond what the schema already provides.

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

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

The description names a specific resource (contact custom fields) and enumerates what is returned (label, API name, type, dropdown choices), so the agent knows exactly what this tool produces. It does not explicitly contrast with a sibling, but none of the siblings touch custom fields, so differentiation is implicit rather than stated.

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

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

It hints at downstream usage ('Use the name as a key in customFields'), which implies the tool is a lookup to resolve field identifiers. However, there is no explicit when-to-use, when-not, or alternative named, so usage is only inferred.

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

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

readOnlyHint=true already establishes this as a safe read. The description adds two things beyond the annotations: the return metadata field totalByStageId and the upstream endpoint GET /v1/deals. It says nothing about pagination behavior (the `next` token the schema alludes to) or response shape otherwise, so the added value is modest.

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

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

Three compact sentences with the resource and its fields front-loaded, then filters, then return note and endpoint. No filler, though the telegraphic fragment style is terse rather than richly 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?

With no output schema, the description does step in to mention totalByStageId in the response metadata, and the filter surface is covered by the schema. Minor gaps remain around paging (the schema hints at `next` but the description never explains it) and default page size.

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

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

Schema description coverage is 100%, so every parameter (limit, offset, status, userId, personId, pipelineId, includeDeleted, includeArchived) is already documented. The description's filter list (pipeline, user, person, status) merely paraphrases a subset of them and adds no syntax or format detail.

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

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

States a specific verb+resource ('Deals (transactions)') and enumerates the payload it returns (stage, price, people, agents, commission) plus its filter axes. It does not name or contrast itself against siblings like fub_search_people or fub_get_person, so it is clear but undifferentiated.

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?

'Filter by pipeline, user, person or status' implies when the tool is useful, but there is no explicit when-to-use/when-not guidance and no mention of alternatives (e.g., fetching a single deal or a person's deals). Usage is inferred rather than prescribed.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral caveat — that some events are only visible in the FUB app, implying results may be incomplete relative to the UI — plus the underlying endpoint, but says nothing about pagination limits or response shape.

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

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

Three short fragments with no filler, and the core purpose is front-loaded before the caveat and endpoint. Slightly telegraphic, but every sentence carries information.

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

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

For a read-only, zero-required-parameter list tool with 100% schema coverage and no output schema, the description covers purpose, filterable dimensions, and the notable 'app-only events' caveat. The missing piece is any hint about the shape or pagination of the returned event list, which the absence of an output schema leaves unstated.

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

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

Schema description coverage is 100%, so all seven parameters are already fully documented in the schema, including the next/offset preference and the event-type enumeration. The description only echoes filtering by person or type, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (lead events) and enumerates concrete event kinds (registrations, inquiries, viewed/saved properties, website visits), which is more than a restatement of the title. It does not distinguish itself from the sibling fub_send_lead_event or from other list tools like fub_list_calls, so it stops short of a 5.

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

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

"Filter by person or type" describes how to narrow results but not when to choose this tool, which is guidance that belongs to the schema anyway. There is no statement of when-not-to-use it or what alternative sibling covers a related need (e.g., fub_list_calls for call events, fub_send_lead_event for writes).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully discloses the payload shape (pipelines plus their stages) and the underlying FUB endpoint GET /v1/pipelines, but says nothing about ordering, pagination, or whether the name filter is exact-match server-side.

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

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

Two compact clauses, front-loaded with the resource and with zero filler; the parenthetical about downstream stage ids earns its place. It is slightly telegraphic, reading as fragments rather than full sentences.

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

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

For a simple read-only list tool with full schema coverage and no output schema, the description covers what it returns and why it matters, which is most of the job. It omits any indication of result volume or pagination and never addresses the name filter, leaving small gaps relative to a one-param tool.

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

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

Schema description coverage is 100% for the single optional 'name' parameter, so the schema already documents it. The description adds no information about the filter's matching behavior, which leaves the baseline of 3.

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

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

The description names the resource (deal pipelines) and, unusually, pre-answers the follow-up question by explaining that the embedded stage ids are what fub_create_deal / fub_update_deal consume. It is a clear noun phrase rather than an explicit verb+resource sentence, and it does not distinguish itself from the sibling fub_list_stages, which overlaps in subject matter.

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 implicitly defines the use case: fetch this when you need stage ids to pass into create/update deal calls, naming the exact downstream tools. There is no explicit 'when not to use' or steering away from fub_list_stages, so it stops short of the top band.

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

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

readOnlyHint=true already covers the safety profile, and the description adds value beyond it: it discloses the return payload includes people counts and gives the underlying endpoint (GET /v1/stages). It does not discuss pagination behavior, though the schema's offset/limit descriptions partially cover that.

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

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

One dense sentence: resource, examples, cross-tool relevance, and endpoint, with the core purpose front-loaded. Nothing is redundant with the title or schema.

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

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

For a simple read-only list tool with no output schema, the description supplies the missing return-content hint (people counts) and the cross-tool semantics. Pagination/navigation details live in the schema, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so sort/limit/offset are fully documented in the schema itself. The description adds no parameter syntax or format detail, which is the expected baseline when the schema does the heavy lifting.

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

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

Names a specific resource ('Contact lifecycle stages') with concrete examples (Lead, Nurture, Past Client, Trash) and frames it as the canonical stage vocabulary other tools consume. An agent can immediately distinguish this from sibling list tools like fub_list_pipelines or fub_list_users.

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 ties the returned names to 'stage' parameters of fub_search_people and fub_update_person, which tells an agent when to fetch this (to resolve/validate stage values). It stops short of stating an explicit 'call this before update_person' directive, so it's strong context rather than a full when-to-use rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered elsewhere. The description adds only the backing endpoint (GET /v1/tasks) and the due enum values; it says nothing about pagination behavior, result ordering, or rate limits, so it adds limited behavioral context beyond 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?

Three compact fragments, front-loaded with the resource and followed by filter scope and endpoint. No padding, though the trailing endpoint reference is of marginal use to an agent.

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

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

For a read-only list tool with full schema coverage, the description covers purpose and filter scope adequately. With no output schema, return shape is undocumented anywhere, and pagination (the schema's `next` hint for deep paging) is never surfaced, leaving a small gap.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description's restatement of filter categories and the due enum values (today|overdue|upcoming) duplicates what the schema already provides rather than adding syntax or format detail.

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

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

States a specific verb+resource (list tasks) and clarifies scope by naming what counts as a task (follow-ups, calls, showings), which helps separate it from siblings like fub_list_calls and fub_list_appointments. It stops short of explicitly contrasting itself with those siblings, so it lands at 4 rather than 5.

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

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

It enumerates the available filter dimensions (person, assignee, type, completion, due window), which implies how to narrow a query, but gives no when-to-use guidance, no when-not-to-use, and no routing to alternatives such as fub_list_calls or fub_search_people. Usage is inferable but unstated.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful context the annotations lack: message bodies may be withheld by FUB for privacy, and it names the backing endpoint. It still says nothing about pagination behavior or ordering, so it does not reach the 4-5 band.

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

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

Two tight sentences with the resource and its filter scope front-loaded and no padding. Slightly telegram-style, but every clause carries information.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers the key surprise (bodies may be hidden) and the resource scope. Pagination/ordering behavior and the return shape are unaddressed, but the schema's offset note ('prefer `next`') partially covers that gap.

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

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

Schema description coverage is 100%, so all five parameters (limit, offset, personId, toNumber, fromNumber) are already documented in the schema. The description only gestures at 'a person or a phone number' without adding format or semantics beyond that, so the baseline 3 is correct.

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

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

States a clear verb+resource (list text messages) and scopes it to 'a person or a phone number', plus the underlying endpoint GET /v1/textMessages. It does not explicitly contrast with siblings like fub_list_calls or fub_log_call, so it falls short of the top band.

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, no prerequisites, and no mention of alternatives (e.g., fub_list_calls for voice). Usage is only implied by the resource name and the person/phone filter hint, which is the minimum-viable-at-best level.

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

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

readOnlyHint=true already establishes a safe read operation. The description adds no behavioral context beyond that: no auth requirements, rate limits, pagination behavior, or return format are disclosed; 'FUB: GET /v1/users' largely restates the annotation's implication.

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

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

Two short fragments with no filler: the first defines scope and purpose, the second gives the API route. Information is front-loaded and every element earns its place.

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

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

For a simple, read-only list tool with a fully documented 6-parameter schema and a readOnlyHint annotation, the description covers what the tool returns and why to call it. It leaves out return shape and pagination behavior, but limit/offset are already documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description does not document any of the six parameters. The mention of 'agents, brokers, lenders' loosely maps to the role filter, but it does not add syntax or meaning beyond the schema's own role description.

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

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

The description identifies the resource (users in the account, i.e., agents, brokers, lenders) and the endpoint GET /v1/users, and the title supplies the verb 'List.' It clearly explains the returned entity and its role for assigning people, tasks, and deals, but it does not differentiate from other list or retrieval siblings such as fub_search_people or fub_get_identity.

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

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

It states a concrete use case—obtaining IDs to assign people, tasks, and deals—which tells an agent when to reach for this tool. It does not name alternatives or exclusions (e.g., when to use fub_search_people or fub_get_identity instead), so it stops short of explicit 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 supply only destructiveHint=true, so the description must carry the rest. It discloses the mutation nature via 'Record' and the POST endpoint, plus the non-dialing behavior, but says nothing about side effects (timeline/activity entries), permissions, or whether an existing call can be overwritten — leaving the destructiveHint unexplained.

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

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

Three tight sentences with zero filler, front-loading the purpose, then the clarification, then the endpoint reference. Nothing needs to be trimmed or moved.

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 10-parameter creation tool with no output schema and sparse annotations, the description covers purpose and the key non-behavior but omits side effects, the significance of destructiveHint, and any guidance on the partially documented parameter set.

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 60% across 10 parameters, so the schema does much of the work, and the description adds only 'with its outcome' as a nod to the outcome enum. It gives no guidance on the required triple (personId, phone, isIncoming) or on the undocumented fields like toNumber/fromNumber.

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 ('Record a phone call made or received outside FUB, with its outcome') and immediately disambiguates the most likely confusion by saying 'Does not place a call.' It also names the backing endpoint (POST /v1/calls), which pins it as the write-side counterpart to fub_list_calls.

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 negative clause 'Does not place a call' usefully rules out a misread (dialing), and 'outside FUB' scopes the use case to offline calls. However, it never states prerequisites (e.g., the person must already exist) or points to a sibling for anything adjacent, so usage is only implied.

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

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

readOnlyHint already declares this a safe read, and the description adds real behavior beyond it: AND combination of criteria, partial-match name semantics, newest-first ordering, Trash exclusion by default, and the default-field-subset quirk with the fields escape hatch. Lacks only pagination/return-shape notes.

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

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

Front-loaded with the core purpose, then packs five distinct behavioral facts into compact sentences with no filler. Slightly dense but every clause carries information.

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

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

For a 25-parameter read tool with no output schema and no annotations beyond readOnly, the description covers the crucial defaults and field-selection behavior. It stops short of describing return shape or deep-paging implications, though the schema handles next/offset.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by documenting cross-parameter logic (AND combination, partial matches) and the fields mechanics ('allFields' / comma list) that the schema does not express.

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

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

States a specific verb (Search) and resource (contacts and leads) and clearly distinguishes the collection-search from the singular fub_get_person via the plural 'contacts and leads'. It does not, however, explicitly name sibling alternatives, keeping it short of a 5.

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

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

Gives useful operating context (criteria combine with AND, name filters partial, default sort, Trash excluded unless includeTrash). But it never says when to prefer this over fub_get_person, fub_check_duplicate_person, or how it relates to sibling lookups.

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

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

With only destructiveHint=true in annotations, the description carries the behavioral burden well: it discloses de-duplication keys, Lead Flow routing, agent notification, action-plan execution for Registration/Inquiry, and the non-obvious 204 semantics (archived source → event silently ignored). It also warns that events older than a day are historical and skip workflows.

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

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

A single dense paragraph, front-loaded with the primary action and then layering behavioral caveats; every sentence carries distinct information. It is information-dense rather than padded, though the run-on structure makes the routing/notification clauses slightly harder 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?

For a 10-parameter, nested-object write tool with no output schema, the description covers the important behavioral and response semantics (de-dup, side effects, 204). It leaves out auth/permission requirements and what a successful non-204 response returns, which an agent would need for full error handling.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns credit for adding cross-parameter meaning — that emails/phones drive de-duplication while person.id targets an existing contact, and that Inquiry types are auto-resolved to Property/General Inquiry. It does not add format guidance beyond what the schema already documents.

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

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

States a specific verb and resource ('Add a new lead or record activity on an existing one') and explicitly frames it as 'FUB's documented way to create leads', which separates it from siblings like fub_update_person or fub_create_deal. The underlying endpoint (POST /v1/events) pins down exactly what is being invoked.

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

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

Gives clear selection context: use it to create a lead, use person.id to target an existing contact, and note that FUB de-duplicates by email/phone. It stops short of naming an alternative for the adjacent case (e.g. modifying an existing person's fields via fub_update_person) or stating when not to send an event.

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 destructiveHint=true annotation covers the safety profile, and the description adds genuine behavioral value beyond it: 'peopleIds/userIds replace the full list' discloses replace-not-append semantics, and 'PUT /v1/deals/{id}' signals full-representation update semantics. It does not mention auth requirements or what happens to omitted fields, but the replace disclosure is the critical non-obvious trait.

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

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

Two tight sentences, front-loaded with the core action, followed by the key behavioral caveat and the API mapping. Every clause earns its place, though the 'FUB: PUT /v1/deals/{id}' shorthand is somewhat cryptic as trailing metadata.

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

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

For a 14-parameter mutation with no output schema and destructiveHint set, the description covers the operation and replace semantics but omits auth requirements, treatment of unspecified fields, and any date-format or validation expectations. Adequate but leaves real gaps for a wide update surface.

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 21% on 14 params, so the schema does not carry the burden. The description groups parameters (stage, price, dates, people, agents) and clarifies replace semantics for peopleIds/userIds, but leaves the many date fields (possessionDate, dueDiligenceDate, earnestMoneyDueDate, finalWalkThroughDate, mutualAcceptanceDate), commissionValue, name, and description without any added meaning or format 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 a specific verb and resource ('Update a deal') and enumerates the mutable categories: stage, price, dates, people, agents. The resource 'deal' clearly separates it from sibling mutators like fub_update_person and fub_update_task, though it never names those siblings 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?

There is no explicit guidance on when to use this versus fub_create_deal (new deal) or fub_update_person (record edits). Usage is only implied by the verb, and no prerequisites, exclusions, or alternative routing are given.

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

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

With annotations carrying only destructiveHint=true, the description does the heavy lifting: it discloses that tags/phones/emails replace rather than append (and that existing entries must be resent), that contacted=true pauses action plans, and that source/sourceUrl are immutable after creation. These are exactly the destructive side-effects an agent must know before mutating, 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?

The text is dense and front-loaded, leading with the replacement caution that carries the most risk and then layering immutable-field and workflow notes. Every clause earns its place with no filler or repetition of the tool title.

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

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

For a 19-param destructive mutation with no output schema, the description covers the dangerous semantics, points to fub_list_stages and fub_list_custom_fields for valid values, and identifies immutable fields. It omits guidance on multiple unlisted parameters (price, addresses, assigned*), so it is strong but not 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 description coverage is low (32%) across 19 parameters, so the description must compensate; it adds real meaning for the highest-risk params (tags, mergeTags, phones, emails, contacted) and even documents source/sourceUrl, which are absent from the schema. However, most parameters (price, stage, addresses, assignedTo, background, customFields, assigned*) receive no added explanation, leaving the compensation partial.

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

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

The description states a specific verb and resource – 'Update a contact's fields' – which is unambiguous against CRUD siblings like fub_get_person or fub_create_deal, and it names the underlying PUT /v1/people/{id} endpoint. It never explicitly contrasts itself with fub_update_deal or fub_update_task, so it falls short of the top band.

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

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

The description explains conditional behaviors (mergeTags, contacted) but never states when to reach for this tool versus fub_get_person, fub_update_deal or the other update siblings. Usage is implied by the name rather than guided, so this sits at the minimum-viable level.

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

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

Annotations already declare destructiveHint=true, so the mutating nature is known. Beyond that the description adds nothing behavioral — no statement of whether this is a partial or full replacement (the 'PUT /v1/tasks/{id}' notation conventionally suggests full replacement while every field except id is optional), no permission requirements, and no note that omitted fields may be cleared.

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

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

A single front-loaded sentence naming the operations, plus the endpoint as a compact suffix. Every clause earns its place with no filler.

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

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

For a 7-parameter mutation tool with low schema coverage and no output schema, the description covers the main actions but omits partial-vs-full update semantics, what happens on success, and one parameter (personId). Adequate to invoke, not sufficient to invoke confidently.

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

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

Schema coverage is only 29%, so the description has to carry weight — and it largely does by mapping actions to parameters (isCompleted, name, type, assignedTo/assignedUserId). It does not mention personId or assignedTo vs assignedUserId disambiguation, so the compensation is incomplete rather than thorough.

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

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

States a specific verb (update) and resource (task) and enumerates the concrete update operations — mark complete, rename, retype, reassign — which maps directly onto the schema's optional fields. Sibling differentiation from fub_create_task and fub_list_tasks is implicit in the verb, not explicit, so it falls short of a 5.

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

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

The listed operations ('mark it complete, rename, retype or reassign') imply the scenarios the tool covers, which is useful. But there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as create_task for new tasks or list_tasks for reads.

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