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

Goes well beyond the annotations: discloses that notes are client-visible in the dashboard, that the action is recorded in workspace Logs with who/IP/time, and the 5000-character cap. That audit-trail and visibility detail is the kind of side-effect context annotations cannot convey. It does not say what the call returns or whether repeated identical calls create duplicates (annotations already flag idempotentHint=false).

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

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

Three short sentences, front-loaded with the action, then side effects, then the alternative — no filler. The character limit is the only near-redundant clause, and it functions as a guardrail reminder.

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

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

For a single-purpose mutation with no output schema and 100% schema coverage, the definition supplies the crucial missing pieces: visibility, audit logging, and size limit. Only the return value/shape and permission requirements are left implicit.

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

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

Schema coverage is 100% and every parameter, including the nontrivial authorName explanation, is documented in the schema itself. The description only restates the 5000-character limit already present in the text property, adding no new semantics. Baseline 3 applies.

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

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

States a specific verb and resource — 'Add a note to a conversation's notes timeline' — and immediately scopes the audience (workspace team and clients). An agent can distinguish it from list_conversation_notes, update_conversation_note, and delete_conversation_note 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?

Explicitly routes away from update_conversation with the reason ('cannot change notes'), which is exactly the comparative guidance an agent needs. It stops short of distinguishing this add path from update_conversation_note (creating a new note vs. editing an existing one), leaving one inference for the agent.

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 flag the whole tool as destructive, but the description decomposes behaviour per action: get is a safe read that never returns secrets or provider keys, update_* are partial merges where only sent fields change, reset clears the login page, and upload copies to the CDN with stated per-kind size/format limits. It also adds the operational caveat "Confirm the brand values with the user before changing a live portal" and the https-only URL rule, none of which are in 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?

The core block is front-loaded and information-dense, but it is a single semicolon-chained paragraph, and the trailing "Actions: ..." list then restates the same behaviours already described, duplicating several sentences. The tool is genuinely complex, yet roughly a third of the text is 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?

Covers all four actions, their merge vs replace semantics, the prerequisite that assets must be uploaded before being referenced, and what upload_asset returns. With no output schema, it could say slightly more about what get hands back beyond "domain status", but an agent has enough to call it correctly.

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

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

Schema coverage is already 88%, so the schema carries most of the weight, but the description adds real meaning: font fallback order with a worked example (["Rubik","Almarai"] = Latin vs Arabic), primaryColorHex building the whole palette, mediaSide being logical (start = left in LTR, right in RTL), and the split-layout gradient fallback when mediaUrl is absent. Upload size limits (≤1 MB, ≤256 KB, ≤2 MB) are stated only here, not in 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 opening sentence gives a concrete verb and resource: "Brand the caller's own whitelabel agency (client portal + login page)", then anchors it to the dashboard equivalent. The scope constraint "Never another agency; whitelabel clients cannot use it" separates it from the generic agency_read/agency_write siblings.

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

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

Each action is given a use case (get for current state, update_branding for logos/colour/fonts, upload_asset before passing URLs to the update actions), and two exclusions are stated: other agencies and custom domains, which go through the dashboard. It stops short of naming agency_write as the alternative route for other agencies, so the routing is inferred rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value by flagging that this returns a 'raw document' and contrasting with agency_branding which 'never returns secrets' — implying this one may expose sensitive data. It stops short of stating what fields or how sensitive, so not a 5.

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

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

Three compact clauses, front-loaded with the core action and scope, then the alternative and the disambiguations. No redundant restatement of the title or annotations.

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, and the description tells the agent it returns a 'raw document', which is enough to set expectations. A hint about the document's shape or secret exposure would make it complete, but nothing needed to invoke the tool correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description usefully clarifies that the implicit input is 'this workspace secret', which frames how the tool is scoped even with an empty 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 ('Get the current agency account') and immediately scopes it to 'this workspace secret (raw document)'. It explicitly names the siblings it is not — agency_branding, orgs_read, clients_read — so an agent can distinguish it 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?

Explicitly routes the agent: use agency_branding when the goal is branding (logo, colours, fonts, language, login page), and notes it is typed and never returns secrets. It also distinguishes the tool from orgs_read (child organizations) and clients_read (end-user accounts), covering the main ambiguity cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds useful behavior beyond them: upsert requires a name, branding fields are validated elsewhere, and certain fields are immutable here. It does not describe return values or deletion permanence, but annotations already flag destructive behavior.

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

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

The description is front-loaded with the core action and uses the remaining sentences for high-value routing and field constraints. Every sentence earns its place, with no redundant restatement of the tool name or annotations.

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

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

Given the destructive annotation and absence of an output schema, the description covers purpose, alternatives, and key field restrictions well. The main remaining gap is that the nested agency payload is still not fully described, though the critical field exclusions are stated.

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

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

Schema coverage is 50%, and the description clarifies that the action supports upsert/delete and that upsert needs a name. However, the agency object is a passthrough with a vague schema description, and the description lists what cannot be changed rather than enumerating allowed agency fields.

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

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

The description gives a specific verb and resource: create/upsert or delete the agency account. It clearly distinguishes this tool from agency_branding, orgs_write, and clients_write, so an agent can identify its role without opening schemas.

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

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

It explicitly routes branding work to agency_branding and org/client CRUD to orgs_write / clients_write. It also states exclusions such as domain claims, verification flags, secrets, and provider keys, which are not changeable here.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds the return-field hints for 'list' (id, date, author) and the restorability note for prompt_history, but says nothing about the 'mode' tradeoff (truncation vs full payload) or about pagination/size limits.

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

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

Purpose is front-loaded in the first clause, followed by usage guidance and a compact action legend. No filler sentences; 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?

With no output schema, the description usefully sketches what each action returns. Minor gap: nothing about agentId scope or the size implications of 'mode', which matter for a read tool that can return bulky blobs.

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 33%, but the description compensates by defining what each action value yields ('latest — the most recent backup', 'prompt_history — ... snapshots that can be restored'). It leaves 'mode' to the schema (which documents it fully) and adds nothing for agentId, so it stops short of perfect.

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 ('Read') and resource ('backups and prompt history of an agent'), and the enumerated actions make the scope concrete. It is clearly distinguishable from the sibling agent_backups_write.

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

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

Gives explicit usage context: 'Check here before a risky change, or to find a version to go back to.' That names the trigger conditions well, though it never explicitly points to the write sibling as the alternative for restoring.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds substantive detail the annotations cannot convey: which action overwrites the whole agent (restore) versus only the prompt (revert_prompt), that create captures the agent 'as it is now', and that set_prompt_caching affects cost/latency. It stops short of stating permissions, reversibility of a restore, or what a successful response returns.

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 warning about destructive overwrites is front-loaded, followed by a compact pipe-delimited action catalogue — no filler sentences. The single run-on caution sentence is dense but every clause carries distinct operational meaning.

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

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

For a 6-parameter, destructive, no-output-schema tool, the description covers action semantics, prerequisites, ID sources, and user-confirmation requirements. The only omission is the 'mode' parameter's relevance to this tool's responses, which is a minor gap.

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

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

Schema coverage is 67%, and the description compensates well for the undocumented action and agentId fields by mapping each action to its required ID (backupId for restore, snapshotId for revert_prompt, enabled for set_prompt_caching). The one gap is 'mode', which is documented only in the schema and never mentioned in 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 opening line states a specific verb pair and resource ('Back up or roll back an agent') and then enumerates all four actions with one-line summaries. It also differentiates from siblings by naming update_agent as the tool whose edits precede a backup and pointing to agent_backups_read / prompt_history as the sources of the required IDs.

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 sequencing guidance ('Take a backup BEFORE large edits with update_agent') and an explicit caution for the destructive actions ('confirm with the user and create a backup first'). The action list tells the agent exactly which action to pick for each goal, with no reliance on inference.

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

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

Annotations already declare that the tool is not read-only, is open-world, not idempotent, and non-destructive. The description usefully clarifies that create makes a new agent from the template as-is, but it does not mention duplicate-creation behavior, permissions, or side effects, which leaves meaningful behavioral 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?

Front-loads the resource and then lists actions compactly with parenthetical details. The final sentence is a focused routing instruction, and there is no unnecessary 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 two-action tool with no output schema, the description covers the essential purpose, actions, key create parameter, and the main alternative tool. It is not fully complete because it omits the mode parameter and gives limited detail on what listing returns beyond templateId.

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

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

With only 40% schema description coverage, the description compensates for some key parameters by explaining action values, templateId's role in create, and that title/description are optional for the new agent. It does not cover mode at all and does not fully explain title/description semantics, so compensation is 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?

Names the resource (ready-made agent templates in the gallery) and enumerates both actions with specific outcomes: listing templates with templateId and creating a new agent from a template. It also explicitly distinguishes itself from create_agent_from_template, so the agent can tell which tool to select.

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 action-level context for list vs. create and explicitly routes custom-agent creation to create_agent_from_template instead. It lacks a fuller when-not explanation for choosing gallery creation vs. other agent-creation paths, but the key alternative is named.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, so the mutation and non-idempotency profile is already known. The description adds that this is a delegation action, but says nothing about permission requirements, whether prior assignment is overwritten, or what the caller gets back—gaps that matter for a mutation with no output schema.

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

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

A single ten-word sentence that front-loads the action and resource with no filler. Conciseness is good, though brevity here borders on 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?

The tool has 4 parameters and no output schema, and the description omits the response shape, permission needs, and reassignment behavior. With annotations covering the safety profile and the schema covering parameters, the definition is adequate but leaves real operational gaps.

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

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

Schema description coverage is 100%, so agentId, convoId, delegatedBy, and assignToUserId are all documented in the schema. The description only implies assignToUserId meaning via 'to a user'; it adds no format, constraints, or semantics about delegatedBy beyond what the schema says. Baseline 3.

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

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

The description states a specific verb (assign) and resource (conversation), and adds the target (a user) plus intent (manual delegation). It is clearly distinguishable from siblings like update_conversation or send_handoff_reminder, though it doesn't explicitly name the closest alternative.

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?

'For manual delegation' implies the usage context, but there is no explicit when-to-use guidance, no prerequisites (e.g., the conversation must exist, the user must be in the workspace), and no comparison to the many sibling conversation tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety and idempotency profile is covered. The only added detail, the 20-item cap, is already in the schema via maxItems=20; nothing is said about partial-batch failure, per-item error handling, or whether URL/sitemap sources are fetched asynchronously. Adequate but not additive.

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 zero filler; the capability and its constraint come first, then the sibling routing. Every clause earns its place and nothing is padded.

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

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

For a batch mutation with a nested item schema, 0% schema description coverage, and no output schema, the description omits everything an agent would want before calling: how results are reported for 20 items, what happens if some docs fail, and what each doc object field means. The routing to siblings is complete, but the invocation-side context is thin.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and does not: it never explains that `docs` is an array of objects requiring at minimum a `name`, nor what `sourceType` (doc/url/sitemap), `urls`, `content`, `tags` or `metadata` do. It also says nothing about `agentId`, the required target. The only hint is the phrase "up to 20", which merely restates maxItems.

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 ... KB documents") plus the scope of the operation ("up to 20 ... in one request"). The two following sentences explicitly name the sibling tools it is not, so an agent can distinguish it from create_kb_doc and create_kb_from_urls 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 explicit routing rules: many website URLs → create_kb_from_urls; a single doc → create_kb_doc. Both the when-to-use-this and the when-to-use-something-else cases are covered, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description's 'Destructive and irreversible' mostly restates that, though 'irreversible' adds a nuance beyond the hint. It says nothing about partial-failure behavior, batch limits, or required permissions, which matter for a bulk destructive call.

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: action, endpoint, alternative preference. Nothing is wasted and the destructive warning is not buried.

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

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

For a destructive bulk operation with no output schema and zero parameter documentation, the definition covers the essentials (what it does, that it is irreversible, which sibling it replaces) but omits batch size limits, partial-success semantics, and auth requirements an agent would want before firing 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%, so the schema gives only names and types for docIds and agentId. The description adds no semantics for either — no mention of what agentId scopes, whether all docIds must belong to it, or how missing/invalid IDs are handled.

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

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

States a specific verb and resource with its bulk scope ('Delete many KB documents in one call') and even names the endpoint. It is immediately distinguishable from the singular delete_kb_doc sibling.

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?

'Prefer over looping delete_kb_doc' explicitly names the alternative and the condition that selects this tool. It does not state any when-not cases (e.g. single-doc deletion threshold or size limits), so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: latency and transcript data on get are only available with mode="full", and transcripts on export require includeTranscripts=true — both are non-obvious side effects an agent would otherwise miss. It stops short of describing output shape or pagination termination 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?

Three compact parenthetical clauses, one per action, with the sibling-routing exclusion front-loaded at the start and end. Dense but every clause carries information; the nested quoting around mode="full" makes it slightly harder to scan than it could be, 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 17-parameter branching tool with no output schema, the description covers the essential decision surface: what each action does, which options are action-specific, and where not to look. Missing is the per-action parameter applicability matrix and any note on what a call log record contains beyond transcript/latency, which would be needed for full completeness.

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

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

With 17 parameters and only 53% schema coverage, the description usefully maps the filter families (agent, type, phone numbers, date range, search) and pins down the mode/action interaction ("transcript and latency data only with mode="full"") plus export options. It does not resolve which filters apply to which action — e.g. whether page/limit are honored during export or whether search is list-only — leaving a meaningful gap on a 17-param 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?

Opens with a specific verb and resource ("Read voice call logs of the workspace") and immediately delimits scope with the call types (web, inbound, outbound). It also names the sibling it excludes — "Chat conversations are in list_conversations, not here" — so an agent can separate it from the conversation tools 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?

The three actions are given with the conditions that select them: list with filters and pagination, get with a callLogId for a single call, export for many calls in JSON/CSV. It also states the routing rule to the alternative tool for chat data, which is exactly the when-not guidance an agent needs.

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

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

Annotations cover the safety profile (destructive, non-idempotent, openWorld), but the description adds what annotations cannot: delete is permanent, agent_id and start_time are immutable on update, and phone numbers are null for web calls. That is the field-level consequence data an agent needs before mutating.

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 verb/resource, then per-action parentheticals in a predictable order. The parenthetical for create is dense and multi-clause, but no sentence is filler — the one candidate for trimming is the schema-redundant 'callLogId; permanent' phrasing.

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

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

For a destructive, non-idempotent mutation over a nested object with no output schema, the description covers required fields, immutability, permanence, and the sibling alternative. What it leaves unstated is what a create/update returns and how the 'mode' parameter interacts with these writes.

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

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

Schema coverage is 75% and the nested callLog object has no documented properties, so the description carries real weight: it names the required create fields, the enum values for type, the ISO format for start_time, and the null rule. It omits any mention of the 'mode' toggle, which is documented in the schema but never connected to these operations.

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 the exact verb set and resource (create/edit/delete a call log record) and immediately contrasts with the sibling that could be confused for it (start_outbound_call). An agent can distinguish this from call_logs_read and start_outbound_call 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?

Gives per-action guidance (what create needs, what update accepts, that delete is permanent) and an explicit exclusion: 'This edits records only — to place a call use start_outbound_call.' The one ambiguity an agent would have is resolved in-line.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so safety is covered. The description adds useful context beyond that: list is paginated and returns progress counters (totalLeads, contactedLeads, successfulCalls, missingCalls, onGoingCalls), which tells the agent what to expect from a read. It stops short of describing pagination limits or token/response size 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?

Three short clauses, front-loaded with the core purpose, followed by the action breakdown and then the routing/exclusion note. No filler sentences.

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

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

With no output schema, the description helpfully names the return counters for list, and the pagination and mode behavior are covered by the schema. Remaining gap: agentId is required yet its role and whether it scopes the list vs. identifies the campaign owner is unstated, and page indexes are undocumented.

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

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

Schema coverage is 50%: mode and campaignId are documented in the schema, while action, agentId and page are bare. The description compensates for action by explaining the list/get semantics and ties campaignId to get, but says nothing about agentId (required for both actions) or page. Baseline 3 is appropriate given partial schema support.

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 ('Read outbound call campaigns of an agent') and enumerates both actions with what each does. It is immediately distinguishable from campaigns_write and whatsapp_campaigns_read, both of which are named or explicitly excluded.

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

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

Explicitly routes writes to campaigns_write and declares a clear exclusion ('WhatsApp broadcast campaigns are not covered'), so the agent knows both when to use this tool and when to look elsewhere. The list/get split is also spelled out inline.

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

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

Annotations already flag destructiveHint=true, openWorldHint=true and non-idempotent, but the description adds material context those annotations cannot convey: that 'enable' dials real phone numbers, that restart resets to the first lead, that resetConversations=true erases earlier call conversations, and that newly created campaigns are stopped by default. That is exactly the kind of side-effect disclosure an agent needs before invoking a destructive mutation.

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 most decision-relevant information (action list and per-action behavior) is front-loaded in the opening sentence, and the compact parenthetical style keeps a lot of detail dense. Minor waste comes from restating the campaign field list that already exists verbatim in the input 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 destructive, nested-object, six-parameter tool with no output schema, the description covers actions, prerequisites and side effects well. It does not mention the 'mode' parameter's compact/full output behavior or say anything about what the call returns, which leaves a small but real gap given there is no output schema.

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

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

Schema coverage is 67%, and the description explains the semantics of every action enum value plus resetConversations and the campaign field set (including non-obvious values like leadGroupName='all' and HH:mm formats). It does add meaning beyond the schema, though the campaign field list is largely duplicated from the schema's own campaign description rather than extended.

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 set of verbs (create, edit, delete, start/stop, restart) operating on a precisely named resource (outbound call campaign). An agent can immediately distinguish this from campaigns_read, which is the read-only sibling.

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?

Each action is given its own operational semantics: create requires name + leadGroupName and starts stopped unless enabled=true; update is partial; enable places real calls and resumes from where it stopped; restart begins from the first lead. It also states the prerequisite that the agent needs an assigned phone number before starting. The only gap is that it never explicitly routes the agent to campaigns_read for listing/reading.

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 disclose that this is a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds useful context that it repairs/re-syncs webhook configuration, but it does not explain side effects, what existing configuration may be overwritten, or what the result looks like. With annotations covering the safety profile, this is adequate but not rich.

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

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

The description is front-loaded, compact, and every sentence adds useful information. It covers purpose, usage context, exclusion, and payload expectations without unnecessary 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 one-parameter mutation tool with annotations and no output schema, the description gives enough information to invoke it correctly: purpose, timing, exclusion, and expected payload fields. It is only slightly incomplete because it does not describe return behavior or side effects in more detail.

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. The description goes further by explaining that the payload is the full request body for /utils/twilio/check-number and typically includes phoneNumber or phoneNumberSid, which adds practical guidance beyond the schema's generic object definition.

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

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

The description clearly states a specific action: repair / re-sync the Twilio SMS/voice webhook configuration for a number. It also distinguishes the tool from WhatsApp Cloud API health checks. However, it does not distinguish this from the sibling sync_sms_twilio_number tool, which could otherwise seem related.

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

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

The description gives a clear usage context: use it when call/SMS routing breaks. It also includes an exclusion by stating it does not check WhatsApp Cloud API health. It does not, however, mention alternatives such as sync_sms_twilio_number, import_twilio_number, or release_twilio_number.

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

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

Annotations already declare readOnly, idempotent, non-destructive, which covers the safety profile. The description adds useful behavioral context about cost: compact is token-cheap with named fields (id/name/email/orgId), while full is heavy. It doesn't describe pagination behavior, but it adds real value 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?

Roughly three sentences, front-loaded with the verb+resource and actions, followed by mode guidance and the sibling exclusions. Every sentence carries distinct value with no waste.

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

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

No output schema exists, so the description should describe return shape; it does so partially (compact fields named, full objects heavy). For a 7-param read tool it is nearly complete, with only pagination and clientId usage left 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 only 43%, so the description must compensate. It covers mode defaults and the compact field set, plus steering from list to get for single records, but leaves page, pageSize, clientId, and the orgId filter (only in schema) largely unexplained in 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 states a specific verb (Read) and resource (Convocore client accounts), clarifies the entity as end-user workspaces under an agency/org, and enumerates the three actions (list, get, check_email). It also explicitly distinguishes the tool from its nearest siblings: 'Not for organizations (use orgs_read) or CRM leads (use leads_read).'

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

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

It gives explicit when-to-use guidance: default mode=compact for list, mode=full only when complete objects are needed, and prefer action=get for a single client. It also states when NOT to use it (orgs, leads) and points to the alternatives.

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, readOnlyHint=false, and non-idempotency, so the safety profile is carried structurally. The description adds that IDs/owner/timestamps are server-set and that create requires name+email, but it never explains what a delete removes (login only? conversations, leads?) — the main behavioral question for a destructive tool.

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

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

Two dense sentences: the first states the scope and the action set, the second maps the field groups and closes with the read-tool pointer. No filler and the routing information is placed last where it is easy to find.

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

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

For a three-parameter mutation tool with annotations covering safety and no output schema, the description covers actions, required fields, field inventory, and the read alternative. The remaining gap is delete semantics and partial-update behavior details, which keep it short of complete.

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

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

Schema coverage is 67%, so the schema already documents most fields; the description adds value by grouping clientData into recognizable clusters (login, widgetIDs, canAccess, channels/integrations, org membership, permissions, notifications). It does not clarify the clientId requirement nuances or the deprecated fields, but it is useful orientation above the 3 baseline.

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

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

Names a specific verb set (create/update/delete) and a specific resource (whitelabel client accounts / portal logins), and explicitly distinguishes itself from clients_read. An agent can tell this is the write counterpart of the read tool without opening the schema.

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

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

Explicitly routes reads to clients_read and enumerates the three supported actions, plus states create needs at least name and email and update sends only changed fields. It does not spell out when a delete is appropriate versus deactivating via status, so it falls short of full when/when-not guidance.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description still earns credit by disclosing a non-obvious behavioral rule not present in any structured field: the clone never inherits branding or funnel recipients. It does not cover auth requirements or the fact that a new agent identity is produced.

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 zero filler, front-loaded with the action and its main knobs before the caveats and sibling routing. Every clause carries distinct information.

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

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

For a mutation tool with nested objects and no output schema, the description omits what a successful clone returns (presumably a new agent ID) and how the caller should reference the resulting agent afterwards. The inheritance and sibling-routing notes are good, but the post-call picture is incomplete.

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 33%, but the description surfaces the nested carryOver flag names (kb, voiceConfig, uiEngineConfig) and characterizes overrides as optional, which helps with the nested-object grouping. It does not add range, default, or effect information beyond what the schema already holds — notably the differing defaults (kb=false vs voiceConfig/uiEngineConfig=true) stay only in 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 ("Clone an existing Convocore agent") and scopes it with the two configurable dimensions (overrides, carryOver flags), naming the three flags. It also explicitly distinguishes itself from create_agent_from_template and import_agent, so the agent can separate it from the two nearest siblings.

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

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

"Prefer this over manually recreating" gives a clear preference, and "Distinct from create_agent_from_template / import_agent" rules out two alternatives by name. What's missing is the discriminating condition — when to clone versus start from a template or an import file — so the choice still requires inference.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is partly covered. The description adds useful action-level behavior: validate does not run code, ai_edit returns code without saving, run returns outputs/logs/errors, and save creates or updates 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?

The description is front-loaded and well structured around the workflow and action list. It is dense but appropriately sized for a multi-action tool, though some phrasing is run-on and could be slightly cleaner.

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

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

For a complex 13-parameter tool with nested objects and no output schema, the description covers the essential flow, action requirements, and alternative tool. It does not fully describe return shapes for every action, but it gives enough to call the tool correctly.

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

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

The schema documents many parameters at 69% coverage, and the description adds action-specific requirements such as code for validate/run, agentId/code/userRequest for ai_edit, and agentId/tool for save. It does not explain every parameter, but it meaningfully clarifies the main action-dependent inputs.

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

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

The description gives a specific verb and resource: writing, checking, and running JavaScript code tools that execute inside the agent. It also distinguishes this from create_agent_tool for HTTP API tools, so an agent can tell the two apart without opening both 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?

It gives a clear workflow (validate → run with sample inputVars → save) and names an alternative for HTTP API tools. It also states the required inputs per action, though it does not discuss when not to use save or how this relates to update_agent_tool/delete_agent_tool siblings.

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

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

Annotations declare non-read-only, open-world, non-idempotent, non-destructive, so the safety profile is already carried by structured fields; the description adds real value on top with 'real calls / real SMS, billed' (cost/side-effect disclosure), the 500-lead cap, the message-required-unless-sendMode=agent rule, and the audience-confirmation requirement. It does not describe what happens on partial failure or what the response contains, 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?

The audience/cost framing is front-loaded, and the destructive-scale warning (500 cap, confirm with user) sits before the alternative-tool pointer. It is a dense single paragraph, but each clause carries distinct information; only minor formatting (splitting the channel branches) would improve scannability.

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

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

For a high-blast-radius, 10-parameter, nested-object tool with no output schema, the description covers the essentials an agent needs to invoke safely: source of leads, per-channel requirements, cost, cap, and confirmation. Gaps are the undocumented options/campaignId parameters and the absence of any return-value expectation, which is a modest hole given there is no output 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?

With 10 parameters at 50% schema coverage, the description carries meaningful extra semantics: it explains channel's two modes and their side effects, that message is required unless sendMode=agent, and that leads must be objects carrying a phone field. options, campaignId, and the interaction between from and contactMethodsPriority remain undocumented in both places.

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 (call or text) applied to a specific resource (a list of leads from leads_read) and immediately distinguishes itself from campaigns_write for scheduled/throttled dialing. The channel=call vs channel=sms behavioral split is spelled out, so an agent can tell it apart from send_sms, start_outbound_call, and campaigns_write without opening the schema.

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

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

Explicit guidance on when to use it (bulk one-shot dialing), when not to (scheduled/throttled → use a campaign), prerequisites (leads must come from leads_read and carry a phone like userPhone), and a hard constraint (max 500 per call) plus an operational rule (confirm the audience with the user first). Nothing is left to inference.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior, so the description adds useful domain context: contacts group a person's conversations, get returns channels and consent, timeline returns conversations in order, and audit_log returns merge/unmerge/consent history. It does not cover pagination behavior or rate limits, but it adds substantive behavioral detail 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?

The description is front-loaded with the core definition and then structured with pipe-separated action descriptions. It is dense but efficient for a multi-action tool, with no clearly wasted sentences, though the repeated 'Needs: identityId' phrasing makes it slightly compressed.

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 an 8-parameter, 4-action read tool with no output schema, the description covers the identity model, sibling differentiation, action meanings, and conditional ID requirements. Pagination and mode behavior are left to the schema, which is reasonable, but a little more detail on list results or pagination expectations would make it 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?

With 50% schema description coverage, the description adds important meaning by defining each action value and the conditional requirement for identityId on get, timeline, and audit_log, plus search for list. It leaves page, limit, mode, and multiChannelOnly to the schema, which already documents most of them, but the action and conditional-ID semantics are key additions.

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

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

The description opens with a specific verb and resource ('Read contacts (identities)') and immediately defines the domain object as one person recognised across channels. It explicitly distinguishes the tool from 'leads_read', so an agent can identify its role without opening sibling schemas.

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

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

It names the key alternative ('Different from leads_read (the CRM lead list)') and gives action-level selection guidance for list, get, timeline, and audit_log. It does not explicitly state when not to use the tool or compare it with other conversation-oriented siblings, but the action routing 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 destructiveHint=true and non-idempotent, but the description adds the important qualifier that merge and delete 'cannot be undone automatically' and instructs confirmation, plus it clarifies merge semantics (the source contact disappears, the target is kept). It doesn't explain what happens to data on unmerge or what the response contains, keeping 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?

Front-loaded summary plus the destructiveness warning before the action list, then a compact pipe-delimited breakdown. Every clause carries either a verb, a risk, or a required parameter; nothing is redundant.

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 destructive tool with no output schema, this covers the essential calling information: which action does what, what each action requires, and which are irreversible. It stops short of describing the result of unmerge (whether a new contact is created) or response shape, which would fully close the loop.

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

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

With only 56% schema coverage and no conditional required fields in the schema, the description carries the critical mapping of action to required IDs (sourceIdentityId/targetIdentityId, identityId/convoIds, consentStatus), which is genuinely additive. It leaves mode, agentId, and consentSource to the schema, so it is not fully complete.

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

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

The opening sentence names four specific verbs (merge, split, update consent, delete) operating on a single resource (contact), and the per-action breakdown makes each operation unambiguous. An agent can distinguish this from contacts_read and from sibling write tools without opening the schema.

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

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

Each action is annotated with the parameters it needs, which is effectively conditional guidance, and the description explicitly says to confirm with the user for merge and delete. What is missing is routing guidance relative to alternatives, e.g. when to look up a contact via contacts_read before merging.

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 the safety profile (not read-only, not destructive, open-world, not idempotent); the description adds the consequential behavior: enableNodes is forced true, the model is pinned to claude-haiku-4-5, nodes[0].kb.enabled with maxChunks=3 / maxChunkSize=512 gets set for auto RAG, and vg_instructions will be rejected by the API. Those are non-obvious side effects and hard failure modes disclosed before invocation.

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

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

Front-loaded with purpose and the sibling alternative, and nearly every clause carries a hard constraint. It is dense to the point of run-on — several distinct admonitions are packed into em-dash chains — which slightly hurts scannability for a 23-parameter 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 23-parameter mutation tool with nested objects and no output schema, the description covers the high-risk configuration surfaces (prompt placement, model pinning, KB/RAG, UI Engine, lead funnel) and warns that additionalConfig rejects unknown fields. The remaining gaps — voice, theme, light mode — are fully documented in 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 coverage is 100%, so the baseline is 3 — but the description earns above that by explaining parameter interactions the schema cannot express: systemPrompt is a mirror of nodes[0].instructions, funnelConfig is the supported path for lead alerts, vg_enableUIEngine is a master switch gating the per-element flags. It does not cover voiceConfig, light, theme, or allowRemoveTools, leaving those entirely to the schema.

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

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

States a specific verb+resource ("Create a Convocore agent") and immediately qualifies it as "advanced/raw," which is the distinguishing axis against the sibling create_agent_from_template. An agent can tell which creation path it is on without opening the schema.

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

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

Names the alternative explicitly ("Prefer create_agent_from_template for website/branded agents") and gives the condition that selects it. It also issues negative routing guidance — do NOT use vg_instructions, do NOT create custom HTTP webhook tools for sales alerts — which are exactly the wrong-path mistakes an agent would otherwise make.

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 openWorldHint=true and destructive=false, but the description adds substantial behavior: workspace resolution, the strict template invariants, that vg_* overrides are blocked from additionalConfig, the fixed model, and that the response includes prototypeUrl/tryItUrl with a URL pattern. This is rich context beyond annotations, though it doesn't state auth/rate limits.

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

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

Front-loaded with the key purpose, but the paragraph is dense and sprawling, bundling invariants, defaults, testing guidance, and URL rules into one long block. Every sentence is substantive but the lack of structure makes it hard 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 29-param creation tool with no output schema, the description covers the important gaps: where the workspace comes from, what the response returns (prototypeUrl/tryItUrl) and its URL pattern, and defaults for the key toggles. An agent can invoke this correctly from the definition alone.

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 already 93%, but the description adds real meaning: default behaviors for leadCapture, appendStandardPromptClauses, attachWebSearchTool, ownerNotifyEmails usage, and the fixed chat model. It goes beyond restating schema, though not every one of the 29 params is addressed in prose.

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

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

Opens with a specific verb+resource+scope: 'PRIMARY way to create chat+voice agents.' The word 'PRIMARY' implicitly distinguishes it from the sibling create_agent, and the following sentence pins down that workspace is resolved internally, clarifying the creation model.

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

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

Explicitly states when to use the non-sales path (leadCapture=false, appendStandardPromptClauses=false, attachWebSearchTool=false) with reasoning, and warns against inventing HTTP notify-sales webhooks. It also routes the agent to read_image for the image catalog and mandates tests before declaring done.

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, open-world, non-idempotent mutation, but the description adds substantial behavioral context: exact httpRequest shape, {{var:ID}} interpolation rules, handling of secrets and environment variables, defaultValue behavior, and the 'Unresolved request values' blocking error. It does not contradict 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?

The description is long but appropriately sized for a complex creation tool with nested request construction. It is front-loaded with purpose and requirements, then organized into INPUTS, REQUEST, SECRETS, and verification guidance; every section earns its place.

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

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

Despite the complex nested schema and no output schema, the description covers invocation prerequisites, request construction, secret handling, default behavior, attachment behavior, and verification. It gives an agent everything needed to call the tool correctly.

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

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

Schema coverage is only 67% and the tool has nested objects, but the description compensates thoroughly. It explains tool.fields entries (key, type, in, description, required), variablesIds versus fields, httpRequest fields, bodyTemplate mode, variable references, and attachToStartNode semantics far 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: 'Add an HTTP/API tool to a Convocore agent.' It also distinguishes this from sibling tools by naming create_agent_variable as a prerequisite for variables and test_agent_tool_request for verification. An agent can identify the operation without opening the schema.

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

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

It explicitly states the prerequisite (tool.name + tool.description), the two input modes (variablesIds or fields), and the need to create variables first. It also names the verification tool and explains the default start-node attachment behavior, giving clear when-and-how 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?

Beyond the annotations, the description discloses important behavior: optional inputs send defaultValue, environment variables are stored in defaultValue and never shown to the model, env values are referenced as {{var:VARIABLE_ID}}, and responses mask env values. These details materially help an agent understand side effects and secret handling for a mutating 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 purpose is front-loaded and the later sentences cover genuinely complex behavior around defaults and environment variables. The description is somewhat dense and long for a two-parameter tool, but each section adds operational value rather than repeating structured fields.

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

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

For a non-readonly create tool with no output schema and a largely undocumented nested object parameter, the description provides enough context to call it correctly in common cases, including secret handling and response masking. It does not cover permissions, error behavior, or full variable-type constraints, so a small gap remains.

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 variable parameter is a nested object with no property documentation, so the description carries most of the burden. It compensates well by listing typical fields such as key, type, defaultValue, description, in, required, isEnv, and isGlobal, and by explaining defaultValue and isEnv semantics. It still leaves agentId and some type/value constraints implicit, so it is not complete.

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

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

The description opens with a specific verb and resource: "Add a variable to a Convocore agent." This clearly distinguishes creation from sibling tools such as get_agent_variable, update_agent_variable, and delete_agent_variable. The additional field examples reinforce what is being created.

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

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

The description gives useful operational guidance for environment variables and secret handling, including a dashboard workflow for keeping secrets out of chat. However, it does not explicitly say when to use create_agent_variable versus update_agent_variable or other sibling tools, nor does it state prerequisites or exclusions. Usage is therefore implied rather than fully specified.

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

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

Beyond the annotations, it discloses that the link is private, needs no Convocore login, expires (default 30 minutes), and requires user action in a separate browser session. It also explains the messenger/instagram shared-page behavior and the two whatsappConnectionMode semantics, giving the agent clear expectations about the resulting link's lifecycle and verification requirement.

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

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

The description is front-loaded with the action and user flow, then adds compact reference notes for channel-specific behavior. Each sentence carries operational value for either calling the tool correctly or instructing the user; there is no filler or repetition of structured fields beyond useful context.

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 still covers what the agent needs: it says a url is returned and must be shown to the user, that the user completes the connection externally, and that get_agent_channels must be used to verify completion. Combined with expiry and per-channel notes, nothing essential is missing for correct invocation and follow-up.

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 25%, with just ttlMinutes documented. The description compensates by explaining the channel enum's behavioral meaning (messenger and instagram share a page and depend on a linked Facebook page/Instagram account) and both whatsappConnectionMode values (metaCloudApi default vs metaCoexistence for an already-used number). It also repeats the ttl default, tying it to link expiration.

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

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

The description opens with a specific verb and resource: 'Create a private link the USER opens to connect WhatsApp, Messenger or Instagram to an agent.' It states scope and audience (the user, not the agent), and the later mention of get_agent_channels clarifies this is the link-creation step, not verification or status checking, which separates it from siblings.

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

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

It gives explicit when-to-use and how-to-sequence guidance: create the link, show the url to the user as clickable, tell them to return when done, then call get_agent_channels to confirm before claiming success. It also states what the agent cannot do (log in with Meta on the user's behalf), which prevents a common misuse.

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 disclose that this is a non-read-only, open-world, non-idempotent, non-destructive mutation. The description adds only "new" and "for an agent" without explaining side effects, duplicate-conversation behavior, or required permissions.

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 no wasted words. Its brevity is appropriate structurally, though it leaves important invocation context to other fields.

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

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

The schema and annotations cover required parameters and safety flags, but the description omits when to create a conversation, what the conversation object should contain, and what the call returns. For a mutation tool with a nested object parameter, that leaves meaningful gaps.

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

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

Schema description coverage is 100%, so the schema already defines agentId and the conversation object. The description does not add syntax, constraints, or meaning beyond the schema baseline.

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

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

The description states a specific verb and resource: "Create a new conversation." It is clearly a creation tool among CRUD conversation siblings, but it does not explicitly differentiate itself from tools like list_conversations or update_conversation beyond the verb.

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 or what prerequisites are required. The phrase "for an agent" hints at agentId usage but does not establish context or exclusions.

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

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

Annotations already declare the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). Beyond that, the description discloses that the KB router itself performs scraping for url/sitemap sources, which is genuinely behavioral context an agent would not get from annotations. It omits failure modes, quota limits (get_kb_quota exists as a sibling) and whether repeated calls create duplicates.

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

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

Front-loads purpose, then alternative, then one compact recipe per sourceType. Telegraphic phrasing, but every clause carries a distinct decision rule and 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 an 11-parameter mutation with no output schema, the description covers the hard part — selecting the right sourceType and correct field combination. Minor gaps remain: nothing about what is returned (created doc id), whether the call blocks on scraping, or quota/limit constraints.

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

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

With 100% schema coverage, per-parameter meanings are already documented, so the baseline is 3. The description goes further by specifying cross-parameter dependencies — which fields are required together for each sourceType and that scrapeContent must be true for url/sitemap — information the flat schema cannot 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?

Opens with a specific verb and resource: 'Add one knowledge base source (VG agents).' It immediately scopes to a single source and names the sibling (create_kb_from_urls) it is not, so an agent can distinguish it 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 explicit routing rules: many page URLs → create_kb_from_urls; individual/website → sourceType=url with urls[] + scrapeContent=true; whole-site → sourceType=sitemap with sitemapUrl + maxPages; raw text → sourceType=doc. It also states a negative constraint ('do not paste web-fetched HTML here'), leaving nothing to inference.

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

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

The description adds important behavior beyond annotations: scraping is asynchronous and callers should poll list_kb_docs/get_kb_doc. It also clarifies the KB router scrape and default scrapeContent behavior. It does not cover permission requirements, rate limits, or partial-failure behavior, but annotations already communicate mutation/open-world/non-idempotent traits.

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 dense but front-loaded and highly efficient. Each sentence carries routing, mode, async, or anti-pattern information without 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 complex, non-idempotent, open-world ingestion tool with no output schema, the definition covers the core workflow, alternative tools, modes, and async polling. It leaves some secondary parameter behavior and failure/partial-success handling to the schema and annotations.

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 high, but the description still adds useful meaning by explaining that per_url creates one KB doc per URL while batch makes a single API call with urls[]. It reinforces the 50-URL cap and scrapeContent behavior. Remaining parameters such as tags, metadata, refreshRate, and skipExisting are covered mainly by 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 states a specific verb and resource: adding many website pages to an agent KB via URL ingestion. It explicitly positions itself as the preferred tool for this task and distinguishes itself from scrape_url/create_kb_doc workflows.

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

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

It gives explicit when-to-use guidance, names a clear anti-pattern (web-fetch/scrape_url then paste into create_kb_doc), and points to alternatives for whole-site ingestion (create_kb_doc sourceType=sitemap). It also explains per_url vs batch modes.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=true and idempotent=false, so the safety profile is covered. The description adds workflow context (a backup step after visual inspection) but says nothing about batch limits, duplicate handling, quota consumption, or what happens on repeated calls despite idempotentHint=false.

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

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

Two tight sentences with the purpose and the parenthetical option front-loaded before the workflow caveat. No filler sentences; the second clause rambles slightly but earns its place as a misuse 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 non-idempotent write tool with 5 params, 0% schema coverage and no output schema, the description is far too thin — it omits how images are addressed, what targetDocName does to existing docs, and what a successful 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% for 5 parameters, so the description must carry parameter meaning and does not. It only nods to autoCaption; it never explains images (data vs sourceUrl, mimeType), targetDocName (append vs overwrite), tags, or agentId, leaving the agent to guess at required-parameter semantics.

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 ("Upload images into the agent KB") and flags an optional mode (autoCaption), so an agent can tell this creates image entries in the knowledge base. It does not explicitly distinguish itself from siblings like import_file_to_kb or create_kb_doc, which are the closest overlapping tools.

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

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

It gives real sequencing guidance — call read_image and label the photos in the system prompt first — and adds an exclusion ("not a substitute for looking at them"), which prevents misuse. It still leaves open when to pick this over import_file_to_kb or bulk_create_kb_docs.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: default 30-day window, unix-second timestamps, and that includeTimeSeries adds per-day points. It does not mention pagination behavior or response envelope shape, but the added context is real.

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 that front-loads the core purpose, then the action list, then time-range and time-series defaults. Every clause carries information. Slightly compressed with parenthetical nesting, but no wasted 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 10-parameter, four-action tool with no output schema, the description does most of the needed work: it defines each action, the time-window defaults, and what the aggregated payloads contain. The remaining gap is that it never sketches what 'list' or 'get' return, which matters slightly more given no output 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?

With 70% schema coverage the baseline is 3, and the description earns above that by explaining aggregation semantics per type ('averages/sums for numbers, counts for boolean/enum/string') and clarifying that 'data' takes the metric key rather than the id. It adds no detail on the uncovered parameters (includeTimeSeries flag semantics are only partly explained, startAfterId ignored).

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 ('Read the custom analytics metrics of an agent') and even defines what a custom metric is with concrete examples. It enumerates the four actions, so an agent knows the tool is a multi-action reader. It stops short of naming custom_metrics_write as the mutation counterpart, so sibling differentiation relies on the tool name alone.

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

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

Each action is scoped inline: 'list', 'get (metricId)', 'data (aggregated values for one metricKey...)', 'all_data (same for every metric)'. That gives clear conditions for choosing among the four modes. It does not explicitly state when not to use this tool or point to a sibling for metric creation/editing.

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 destructive annotation, the description discloses important behavioral consequences: changing a metric type can make old data inconsistent, and deleting stops tracking while preserving historical data. It also clarifies enum-specific creation 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?

The description is dense and front-loaded with the overall purpose before breaking down each action. Every sentence carries actionable information, with no filler.

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

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

For a destructive nested-object write tool with no output schema, the definition covers the critical create/update/delete semantics, required fields, and data-integrity caveats. Remaining details such as agentId and mode are either obvious from context or 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 coverage is low at 40%, and the description compensates by mapping action values to required fields and by explaining the metric object structure. It does not explain agentId or mode, but mode is already described in the schema and agentId is strongly implied by 'on an agent'.

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 set and resource: create, edit, or delete a custom analytics metric on an agent. It clearly distinguishes this write tool from the sibling read tool by enumerating mutating actions rather than read behavior.

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 action-specific usage conditions: create needs key + type + description and enum options, update uses metricId plus only changed fields, and delete uses metricId. It does not explicitly route readers to custom_metrics_read or state when not to use this tool, so it stops short of the top score.

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, idempotentHint=false, and openWorldHint=true. The description adds useful irreversibility context with 'permanently,' but does not disclose cascading effects, required permissions, or whether associated data is removed.

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 a single front-loaded sentence with no wasted language. For a simple one-parameter destructive tool, the size and structure are appropriate.

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

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

Given the tool's low complexity, complete parameter schema, and strong destructive annotations, the description is largely sufficient. The main remaining gap is that it does not explain what happens to related resources or whether confirmation is required.

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 schema fully documents the single agentId parameter at 100% description coverage. The description does not add any parameter-specific meaning beyond what the schema already provides, so the baseline score applies.

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

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

The description uses a specific verb and resource: delete an agent, and adds the important qualifier 'permanently.' It distinguishes the target from siblings such as delete_agent_tool by naming a Convocore agent, though it does not explicitly route among related agent tools.

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

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

The description provides no explicit guidance on when to use this tool versus update_agent, clone_agent, or delete_agent_tool. Usage is only implied by the verb 'Delete,' with no preconditions, alternatives, or warnings about when not to use it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is structured data. The description adds the scope exclusion (MCP tools unaffected) and reinforces irreversibility with "Permanently," but says nothing about cascade effects on agents that reference the tool or any auth requirement — comparable to the calibration case where a scoping constraint under annotations earned a 3.

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

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

Two short sentences, zero filler; the destructive action and its scope are front-loaded and the exclusion is the natural second beat.

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 destructive delete with full annotation coverage and no output schema, the definition covers what the tool does, what it targets, and what it excludes. The remaining hole — side effects on agents referencing the deleted tool — is the only thing an agent might reasonably want before calling.

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

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

Schema description coverage is 0%, so the description carries the burden, and it only tells us toolId identifies the agent HTTP tool. It gives no format detail (UUID vs slug vs name) or validation behavior, which is the one gap an agent could hit at call time; for a single obvious required parameter this is adequate but not compensating.

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 ("Permanently delete a Convocore agent HTTP tool") plus the identifying key (toolId), and draws a boundary ("Does not delete MCP tools") that separates it from MCP-related deletion surfaces. It never names the closest siblings (get_agent_tool, update_agent_tool, create_agent_tool), but the HTTP-vs-MCP distinction is enough to select correctly.

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

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

The negative case is implied via "Does not delete MCP tools," which signals when not to use it. There is no positive when-to-use guidance, no prerequisite or permission note, and no pointer to the alternative tool for MCP deletion, so the agent must infer the rest.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The word 'Permanently' reinforces irreversibility, but the description says nothing about cascade effects on agent prompts that reference the variable, behavior when the variableId does not exist, or what is returned.

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

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

A single front-loaded sentence with the destructive qualifier first and the resource second. Nothing is wasted or buried.

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

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

For a one-parameter delete with rich annotations covering destructiveness and idempotency and no output schema, the description supplies the essential scope. Only error/not-found behavior and the source of variableId remain unstated, which are minor for this tool shape.

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

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

Schema description coverage is 0%, so the description must carry the param burden, but 'by variableId' only restates the parameter name and type already in the schema. It gives no format, no hint on where the ID comes from (e.g., list_agent_variables), and no note that it is required.

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

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

States a specific verb ('permanently delete'), a specific resource ('Convocore agent variable'), and the lookup key ('by variableId'). It is clearly distinguishable from delete_agent, delete_kb_doc, and delete_agent_tool by resource, though it does not explicitly name those siblings.

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

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

No guidance on when to use this versus update_agent_variable (to clear a value) or the sibling delete tools, and no prerequisites such as required permissions or confirmation steps. The agent must infer all usage conditions 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds nothing beyond that — it does not say whether deletion is permanent, whether messages/notes cascade, or whether confirmation is required, which matters for a destructive irreversible operation.

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 single sentence is maximally concise but suffers from under-specification rather than tight brevity. There is no wasted wording, but also almost no informational payload.

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

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

For a destructive, non-idempotent deletion with no output schema, the description should disclose permanence, cascading effects, or error behavior. None of that is present, leaving the agent with essentially only the annotations to understand consequences.

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 both required parameters (agentId, convoId) documented in the schema. The description adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

The description 'Delete a conversation' is a verbatim restatement of the title and effectively of the tool name delete_conversation. It conveys the basic verb+resource but offers no differentiation from siblings like delete_conversation_note or delete_agent beyond the noun itself.

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

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

No guidance on when to use this versus alternatives (e.g., deleting a whole conversation vs. individual notes, or whether to archive instead). No prerequisites or warnings stated. The agent must infer usage 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 disclose destructiveHint=true and idempotentHint=true, but the description adds crucial context: any user with access may delete any note, and a full copy with deleter identity, IP, and timestamp is kept in workspace Logs. This soft-delete and audit behavior is not in the annotations and helps the agent understand consequences.

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: the action first, then permission/audit context, then a usage constraint. Every sentence earns its place and the key information 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 destructive tool with annotations covering safety and a fully described schema, the description adds the necessary permission scope and audit retention details. No output schema exists, but none is needed for a delete confirmation. Nothing essential is missing.

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