Assistable

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds nothing beyond that: it does not disclose default range behavior when dates are omitted, sort order, timezone/date-format expectations, or that results are paginated — despite the schema exposing a cursor.

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 sentence with no filler and the scope stated up front. It is efficient, but the economy comes partly at the cost of under-specification rather than being purely tight writing.

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, no annotation detail beyond hints, and zero parameter descriptions, the description carries the full explanatory burden and does not meet it. An agent cannot tell how paging works, what the date string format is, or what a response contains.

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 5 parameters. The description covers only subAccountId and the startDate/endDate pair, and even there adds no format or inclusivity detail. The 'limit' and 'cursor' parameters — the entire pagination contract — are undocumented in both the schema and the 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 gives a specific verb and resource ('List appointments') and states both the scoping constraint (subaccount) and the optional date filter. It is unambiguous on its own, though it does not distinguish itself from any sibling — there is no sibling appointments tool, so this costs little.

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

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

Usage is only implied: an agent infers it should call this when it needs appointments for a subaccount in a window of time. There is no statement of when to prefer it over another tool, no prerequisites, and no note about when the date range should be omitted.

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 say readOnlyHint=false/destructiveHint=false, so the description carries the real burden and does it well: it discloses the returned artifacts (verification_uri_complete, user_code), that a human must approve and pick an account, and that signup is possible. It omits how long the device_code stays valid or what happens on denial/expiry, which keeps it short of a 5.

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

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

Roughly 70 words, front-loaded with the precondition, then the return values, then the next call. No filler sentences; the slight run-on is dense rather than wasteful.

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

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

No output schema exists, so the description must describe returns and follow-up — it names verification_uri_complete, user_code, device_code, interval and api_key, plus the human hand-off step. Nothing an agent needs to complete this half of the flow is missing.

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

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

Schema coverage is 100% and there is only one optional parameter (client_name), so the schema already documents it fully. The description never mentions the parameter or that the agent's name is what the approver sees, adding no meaning beyond the schema — baseline 3.

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

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

States a specific action (start the sign-in/device-authorization flow) with its precondition, and explicitly names the sibling that continues the flow (assistable_connect_finish). An agent can distinguish it from every other sibling 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?

"Only when you have no Assistable API key" gives an explicit when-to-use gate, and the follow-up sentence prescribes the next step: call assistable_connect_finish with device_code every interval seconds until api_key is returned. Alternatives and sequencing are both 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?

Beyond the annotations, it discloses the one-time api_key return, that the key cannot be shown again, how to use it as a Bearer header, and the authorization_pending polling behavior. These are important operational details for a credential-returning 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?

The description is three tightly written sentences with no waste. Critical behavior, polling guidance, and secret-handling instructions are front-loaded.

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

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

For a sign-in completion tool with no output schema, the description covers the return value, error handling, credential usage, and security constraints. An agent has enough information to call it correctly and handle the result.

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

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

Schema coverage is 100% and the single device_code parameter is fully documented in the schema as coming from POST /v3/agent-connect. The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific action: check an assistable_connect sign-in and retrieve an api_key once approved. It is clear enough to distinguish the tool from most siblings, though it does not explicitly name assistable_connect as the initiating tool.

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

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

It gives explicit polling guidance: wait interval seconds and call again when error.code is authorization_pending. It does not mention alternative tools or when not to use this one, but the usage context is clear.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context on top: it creates an account, sends a 6-digit code to the email, requires the agent to ask the user for that code, and is only half the operation (must be completed via assistable_signup_finish). It does not state whether a half-finished signup expires or is retryable, 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?

The gating condition is front-loaded in the very first clause, and the four sentences cover gate, inputs, side effect/next step, and fallback with no filler. Slightly dense for a single paragraph, but every sentence is functional.

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 with no output schema, the description covers the critical unknowns: the two-step flow, the email side effect, and where to go next. Optional fields like client_name and business_name are left entirely to the schema, which is acceptable given 100% coverage, but means the description alone is not a full picture.

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

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

Schema coverage is 100%, so every parameter is already documented, and the description mostly restates the obvious ones (email, name). Its only added value is signaling that area_code OR city/state is the choice for the local number, but it does not say which wins if both are supplied. Baseline 3 applies when the schema carries the load.

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 ('start one [an Assistable account]') and immediately frames the scope with a negative gate: 'Only when the person has no Assistable account.' It explicitly names the sibling it is not (assistable_connect) and the follow-up tool (assistable_signup_finish), so an agent can place it in the flow 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 an explicit when-to-use condition ('no Assistable account'), an explicit when-not with the alternative ('assistable_connect is for people who have one'), and even an error branch that redirects to assistable_connect if the user reports an existing account. Nothing about tool selection 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?

Goes well beyond the annotations: discloses that api_key is returned only once and must be sent as a Bearer header to this server, and that calls/texts return card_required until card_url is opened, which saves the card, adds starting credit, and buys the local number. These are non-obvious side effects and gating rules nothing else in the structured data provides.

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 action, then the credential handling, then the card_url gating, so importance order is right. It is dense with stacked parentheticals and long clauses, which costs a little readability but no sentence is filler.

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

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

With no output schema, the description carries the return-value burden itself and does so: api_key returned once, its header usage, and the card_required state that blocks calls until card_url is opened. Nothing an agent needs before or after invoking 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?

Schema coverage is 100%, so the schema already documents all three parameters, including the 'generate a strong one and keep it in your vault' guidance the description restates. The description adds only framing (code is 'the code the person read to you', password is 'their dashboard login'), which is helpful but largely duplicative; 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 (finish) and resource (assistable_signup), names its three inputs, and explicitly ties itself to the assistable_signup sibling that produces signup_id. An agent can distinguish this from assistable_connect/assistable_connect_finish 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?

Establishes the two-step flow ('Finish assistable_signup...', 'signup_id from POST /v3/agent-signup') and prescribes the follow-up action (send card_url to the person). It gives clear operating context but never states exclusions or names the connect_finish alternative for the parallel flow.

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 and destructiveHint=true, so the safety profile is covered. The description adds genuine value by specifying 'soft-delete', telling the agent the record is not permanently removed — but it omits whether the action is reversible/restorable, what happens to existing conversations or references, and any permission requirements.

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

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

A single compact sentence with the key clarification parenthesized immediately after the verb. No filler, and the most important nuance (soft-delete) is front-loaded.

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

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

For a one-parameter tool with annotations covering destructiveness, the description covers the essentials of what happens. However, with no output schema and an undocumented parameter, an agent still lacks the ID semantics and any post-archive behavior (restorability, side effects) needed to invoke it 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 description coverage is 0% and the single required parameter assistantId is undocumented in both schema and description. The description gives no indication of format, source, or whether the ID is the assistant's unique identifier versus an external reference, so it fails to 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?

The description states a specific verb and resource ('Archive an assistant') and clarifies that archiving means soft-delete, which resolves the main ambiguity an agent would have. It does not differentiate from siblings (e.g., assistants_update), but the operation is distinct enough in the toolset and there is no competing archive/delete sibling to route against.

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

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

There is no guidance on when to choose archive over assistants_update, nor any stated prerequisite or condition (e.g., when an assistant is obsolete vs. merely modified). The agent is left to infer usage entirely from the verb.

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 and destructive=false, so the write nature is known. The description adds real behavioral detail for platform_tools (declarative full-replace, custom tools untouched, [] detaches all) and voice_settings, but says nothing about return values, duplicate-name handling, or what a successful create yields.

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 required parameters and then groups the optional config blocks compactly. Every sentence carries information, though the platform_tools/voice_settings sentences are dense and could be split for readability.

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 create tool with no output schema and 10% schema coverage, the description is only partially complete. It explains the notable behavioral fields but omits several parameters and any sense of the create response or failure modes.

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 10%, so the description must compensate. It covers required fields and several config blocks (llmConfig, voiceConfig, chatConfig, voice_settings, platform_tools) but leaves voiceId, description, and assistantType undocumented in both the description and largely 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+resource ('Create an assistant') and names the required fields, so the agent knows exactly what it does. However, it does not differentiate from siblings like assistants_update or assistants_archive, leaving the agent to infer that this is the creation path.

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?

Offers no when-to-use vs alternatives guidance and no prerequisites beyond the required fields. 'Mirror the dashboard create dialog' gives some context but does not tell the agent when this tool is the right choice versus assistants_update.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds useful behavioral context by naming the response components (voice_settings and platform_tools), which helps the agent understand what data will be returned beyond a generic success indication.

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

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

Two sentences with zero wasted words. The core operation is front-loaded, and the response detail follows naturally without redundancy.

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 one parameter, read-only annotations, and no output schema, the description is largely complete: it covers purpose, input method (by ID), and key response fields. Minor omissions like error behavior or format examples are acceptable 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 0%, so the description must carry the burden of explaining the single parameter. It does so indirectly by saying 'by ID', but it does not specify the format or expected value of assistantId, leaving a 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?

The description uses a specific verb (fetch) and resource (assistant's full configuration) and clarifies the lookup is by ID, which implicitly distinguishes it from assistants_list. It lacks an explicit callout of the sibling tool, but the purpose is unambiguous.

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

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

The phrase 'by ID' implies when to use this tool (when you have an assistant ID), but there is no explicit guidance on when to choose this over assistants_list or other sibling tools, nor any mention of preconditions.

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 and openWorldHint, so safety is covered. The description adds real behavioral value by disclosing the default filtering of archived records and the reduced field set relative to assistants_get — information not present in any structured field.

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

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

Two short sentences, front-loaded with the core action, with the caveat appended. Every clause carries information an agent needs and nothing is repeated from the schema.

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

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

There is no output schema, and the description partially compensates by noting which fields are absent from the list response. However, it says nothing about pagination mechanics despite limit/cursor parameters, nor about what an assistant record actually contains, leaving gaps for a 4-parameter list 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% and none of the four parameters are explained. Only the archived behavior is implied (mapping to includeArchived); subAccountId, limit, and cursor — including that cursor is a pagination token — are left entirely 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 (list assistants) plus the scoping constraint (within a subaccount), and explicitly distinguishes itself from assistants_get by naming the fields only that tool returns. An agent can choose between 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?

It clarifies the default archived-exclusion behavior via '(excludes archived by default)', which implicitly tells the agent when to set includeArchived, and it routes to assistants_get for the richer field set. But there is no explicit guidance on pagination usage or when a list vs. get is appropriate beyond that single note.

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 declaring readOnlyHint=false and destructiveHint=false, the description adds meaningful behavior: partial patch semantics, nested upserting, declarative platform-tool replacement, and the caveat that enable_voicemail_detection is intent-only. It does not cover permissions, atomicity, or error behavior, but it is substantially more transparent than the annotations alone.

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

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

The description is front-loaded, dense, and free of filler. Two sentences cover the update model, the two most complex fields, and the important empty-array detach case without repetition.

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

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

For a mutation tool with nine parameters, nested objects, no output schema, and sparse schema coverage, the description is adequate but incomplete. It covers core patch behavior and the trickiest fields, but does not explain the opaque config blocks or operational details such as permissions and failure modes.

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 11%, so the description must compensate for many undocumented parameters. It explains voice_settings and platform_tools, but leaves assistantId, name, voiceId, description, llmConfig, chatConfig, and voiceConfig largely or entirely unexplained, especially the opaque nested config objects.

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: "Patch an assistant." It is clear this is a partial update rather than create, get, list, or archive. However, it does not explicitly name sibling tools or contrast itself with them.

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

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

The description provides useful update semantics: "Only supplied fields change; nested config blocks are upserted." It also explains declarative behavior for platform_tools, including that an empty array detaches all. It does not state when to choose this tool over assistants_create or other siblings, nor does it give prerequisites or exclusions beyond the field-level behavior.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that a call record includes status, recording, and transcript, which hints at payload weight and possible side-channel media access, but it says nothing about behavior on a missing/invalid ID or whether recording/transcript may be absent.

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 short sentence, front-loaded with verb and resource, with a compact parenthetical for the return payload. No wasted words.

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

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

No output schema exists, so the parenthetical field list usefully stands in for return-value documentation, and readOnly annotations cover safety. However, the unresolved required-parameter ambiguity (0 required, two aliased ID params) is a real gap for an agent trying to construct a valid 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 coverage is only 50% and the description does not compensate: 'by ID' restates what the name already implies. It never explains that callId is a legacy alias for call_id, nor reconciles the fact that the schema marks zero parameters as required despite fetching 'by ID'.

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 'Fetch' plus resource 'call' plus the selector 'by ID', and it names the payload the caller gets back (status, recording, transcript). It is clearly distinguishable from siblings like contacts_get or assistants_get by resource alone, though it does not name any sibling explicitly.

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

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

There is no statement of when to use this versus alternatives (e.g. a list/search tool or conversations_list) and no preconditions or exclusions. The only implied guidance is the 'by ID' selector.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say what happens if the ID is unknown (error vs empty result), what fields a contact contains, or any auth/rate considerations.

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 with zero filler; the verb and lookup key arrive immediately. It is efficient, though so terse that brevity edges toward under-specification.

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 no output schema, the description would ideally hint at the returned contact shape and not-found behavior. For a trivial single-parameter read tool with safety annotations, it is minimally sufficient but leaves the return contract 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?

There is one required parameter with 0% schema description coverage, so the schema gives no format guidance for contactId. The description only echoes 'by ID', adding minimal meaning about identifier form or source.

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 (contact) with the lookup key (by ID), so the operation is unambiguous. It does not differentiate from the sibling contacts_list, which is the main alternative an agent would weigh.

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 statement, no prerequisite (e.g. needing a known contactId obtained elsewhere), and no mention of using contacts_list for discovery. Only the implicit signal of the required contactId parameter hints at 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 openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing the response field meta.total and its meaning, but says nothing about pagination behavior or what happens when limit is exceeded — relevant since a cursor parameter exists.

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

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

Two short sentences, front-loaded with the core action, with the response-semantics tip appended. Nothing is padded and nothing needs trimming.

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

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

There is no output schema, and the description partly compensates by explaining meta.total, which is helpful. But for a paginated list tool with four undocumented parameters, it leaves an agent guessing about page size defaults, cursor reuse, and search matching — gaps the schema does 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 0% and none of the four parameters (limit, cursor, search, subAccountId) are explained in the description — not even the meaning of the required subAccountId or the syntax of search. The only semantic content given is about a response field, not a parameter, so the coverage gap is unmitigated.

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

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

States a specific verb and resource (list contacts) plus a scope (in a subaccount), which is enough to distinguish it from contacts_get. It does not explicitly contrast itself with the sibling getter, but the read-many vs. read-one distinction is inferable from the wording.

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

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

It gives one concrete usage cue — use meta.total to answer 'how many contacts are there' — which is a genuinely useful routing hint. However, it never says when to prefer contacts_get, when not to use this tool, or how paging should be driven.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the subaccount scope and does not explain pagination behavior, result ordering, or what a subaccount boundary implies, leaving meaningful behavioral context undisclosed.

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 a single front-loaded sentence with zero waste, which is appropriately concise for a simple list operation. The brevity, however, reflects under-specification rather than complete economy.

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 paginated list tool with three undocumented parameters and no output schema, the description is too thin. It identifies the resource and scope but omits how pagination works and what the response contains, leaving gaps an agent would need to infer.

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, but it does not explain the purpose or constraints of limit, cursor, or subAccountId beyond the word 'subaccount.' The agent gets no help on pagination or required identifier semantics from either the description or schema.

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

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

The description states a specific verb and resource ('List conversations') and scopes it to a subaccount. It does not distinguish this tool from sibling list tools such as appointments_list or contacts_list, 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?

It gives no guidance on when to use this tool versus alternatives, and no prerequisites or exclusions are stated. The usage is only implied by 'List conversations in a subaccount.'

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful context by stating that it returns up to 5 exact tool definitions with JSON schemas and annotations, and it includes an important caveat that the result is not authorization to invoke the 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?

Three short sentences with no wasted wording. The core search behavior is front-loaded, followed by return details and then the usage warning.

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

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

For a two-parameter read-only search tool with no output schema, the description explains what is searched, what is returned, how many results to expect, and a critical authorization caveat. Nothing essential for correct invocation appears to be 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 both query and limit are already well documented. The description reinforces that the query is task-oriented and that results are capped at 5, but it does not add syntax or formatting details beyond the schema.

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

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

The description uses a specific verb and resource: it searches Assistable's registered MCP tools by task. It clearly distinguishes this meta-search behavior from sibling tools like tools_list and tools_get by framing the search around the user's intended task and promising exact tool definitions.

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 says to use this first when choosing a tool and warns that results are not authorization to call them. It does not name when-not-to-use cases or alternative sibling tools, but the primary usage context is clear.

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

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

Annotations already declare this as a non-read-only, non-destructive write, so the safety profile is covered. The description adds real value with the name regex and subaccount-uniqueness constraint, but says nothing about permissions/auth, what happens on duplicate names, or what creating a custom tool requires (URL, method, etc.).

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 and followed by the key validation constraint. 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 tool with 7 undocumented parameters, nested objects, an enum, and no output schema, the description is far too thin. An agent cannot tell what fields like url, httpMethod, or parameters mean or how to shape them, so it would have to guess.

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 7 parameters, including a nested 'parameters' array and an httpMethod enum, so the description must carry the burden. It only annotates the 'name' parameter (format + uniqueness) and leaves url, httpMethod, headers, parameters, description, and subAccountId entirely unexplained.

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

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

States a clear verb and resource ('Create a custom tool') and pins down the toolType, so an agent knows this is the creation counterpart to tools_update/tools_delete. It stops short of describing what a custom tool actually is (an HTTP-backed endpoint), so it is not fully differentiated in substance.

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

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

No when-to-use guidance, prerequisites, or contrast with siblings such as tools_update or search_tools. The intended usage is only implied by the tool name.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value with "soft-delete", implying the record is retained rather than purged, but it says nothing about whether the tool disappears from tools_list, whether the action is reversible, or what permissions are needed.

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 with no filler, which is appropriate for a one-parameter mutation. It is terse to the point of under-specification, but nothing is wasted.

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

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

For a destructive mutation with no output schema and zero parameter documentation, the description is thin: no return value, no effect on listings, no recovery path for the soft delete, no error behavior. The annotation covers the danger flag but not the operational consequences an agent needs before calling it.

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% for the single required toolId parameter, and the description offers no clarification — it doesn't say whether toolId refers to a custom tool's id versus a built-in tool, or what happens if the id is unknown. With one undocumented parameter the description should have compensated and does not.

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

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

The description gives a specific verb+resource pair ("soft-delete a custom tool") and the qualifier "soft" meaningfully distinguishes the operation from a permanent delete. It doesn't reference any of the many sibling tools (tools_get, tools_update, tools_create_custom), 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?

There is no statement of when to use this versus tools_update (e.g. deactivating vs. removing) or any prerequisite/confirmation guidance. The agent must infer the usage context entirely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful signal that the response is the 'full configuration' (relevant since there is no output schema), but says nothing about error behavior for an invalid toolId or what 'full' includes. With annotations carrying the safety burden, this is adequate but thin.

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 with no filler or redundancy. It is appropriately sized, though the brevity comes at the cost of the missing usage and parameter context noted elsewhere.

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 one-parameter read tool with readOnly annotations, the description is minimally sufficient to call it. However, with no output schema it should describe what 'full configuration' returns, and it should indicate how to obtain a valid toolId.

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 is a single parameter, toolId, with 0% schema description coverage, and the description adds no meaning beyond the obvious name. It does not say the id is the tool identifier returned by tools_list or tools_create_custom, nor its format. This leaves the one parameter entirely dependent on the agent's inference.

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

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

The description gives a specific verb ('Fetch') and resource ('a tool's full configuration'), making it clear this retrieves a single tool record. It implicitly contrasts with tools_list by emphasizing 'full configuration', but never names the sibling that lists tools, so differentiation relies on 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?

There is no explicit guidance on when to use this versus tools_list, search_tools, or tools_update, and no statement of prerequisites such as where toolId comes from. An agent must infer that this is the detail-fetch counterpart to the list operation.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds scope ('visible to a subaccount') and the includePrebuilt filter semantics, but omits pagination behavior, default result ordering, or return shape, which is acceptable given the read-only annotation but still leaves gaps.

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

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

Two short sentences, front-loaded with the core action and followed by the most useful filter hint. No wasted text.

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

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

For a list tool with five parameters, no output schema, and 0% parameter descriptions, the description is incomplete. Pagination via limit/cursor, search semantics, and required subAccountId behavior are not explained.

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 5 parameters, so the description should compensate but only explains includePrebuilt. It leaves subAccountId, limit, cursor, and search undocumented, making it hard to invoke correctly without inspecting 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 ('List tools') plus scope ('visible to a subaccount'), so the agent can distinguish it from mutation siblings like tools_create_custom or tools_update. It does not explicitly distinguish it from search_tools, which limits it to a 4.

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 useful guidance for one parameter ('Pass includePrebuilt=false for only custom tools'), but does not say when to use this versus search_tools or tools_get, nor any exclusions or prerequisites.

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

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

The annotations already establish that this is a non-read-only, non-destructive mutation. The description adds useful non-obvious behavior: parameters and headers are replaced wholesale rather than merged, and omitting them preserves existing rows. It does not disclose effects on other fields, validation behavior, or whether other omitted fields are preserved.

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 core patch semantics front-loaded and the replacement caveat immediately after. There is 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 seven-parameter mutation tool with no output schema, the description is thin: it omits the required toolId, says nothing about the other updatable fields, and does not explain what the tool returns or whether the update is validated. It covers only the replacement behavior of two 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 description coverage is 0% across seven parameters, and the description only explains semantics for two of them (parameters and headers). The required toolId, url, name, httpMethod, and description fields are left entirely to the schema, so the description 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?

The description states a specific verb and resource ('Patch a custom tool'), which clearly distinguishes it from sibling read/list/create/delete tools. It does not explicitly name those siblings, but the mutation scope 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?

It gives partial-update guidance for parameters/headers ('omit to leave them'), which implies how to use the tool for incremental changes. However, it does not say when to choose this over tools_create_custom or tools_delete, nor does it mention prerequisites such as a valid toolId.

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