SkipCalls

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description earns credit by specifying exactly what is destroyed: existing name/notes are overwritten. That is concrete consequence detail the annotations cannot convey. It stops short of saying whether unmentioned fields are preserved or cleared, or what the response contains.

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

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

Four short sentences, each carrying a distinct payload: purpose, destructive consequence, confirmation requirement, prerequisite check. The destructive warning is surfaced near the front rather than buried.

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

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

With no output schema, annotations covering the safety profile, and full parameter documentation, the description covers nearly everything an agent needs before calling. The remaining gap is what a successful upsert returns and whether it reports create-vs-update, which would help the agent relay results to the user.

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

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

Schema description coverage is 100%, so every parameter is already documented, and 3 is the baseline here. The description adds one genuinely new semantic point — phoneNumber is the matching key that determines create-vs-update — but says nothing about how notes interacts with the overwrite behavior.

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 pair and resource ('Create or update a contact') plus the identity key ('by phone number'), and immediately clarifies that this is an upsert rather than a pure create. An agent can distinguish it from get_contact, update_contact and search 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 prescribes two pre-call behaviors: 'Use search first to check if the contact exists' and 'ALWAYS confirm the change with the user before calling.' It names the alternative (search) but does not clarify when to prefer the sibling update_contact over this upsert path, which is the main unanswered routing question.

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

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

Goes well beyond the annotations: discloses that the operation is additive ('other functions stay'), that Code functions run saved tests first and abort attachment on failure, and that secret header values must never be echoed. These are non-obvious failure and safety behaviours an agent could not infer from readOnly/destructive/idempotent hints.

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

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

Front-loaded with purpose, then constraints, then the confirmation requirement in a tight sequence of short clauses. Dense but every sentence carries information; only the display-field enumeration is slightly procedural.

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 only two fully documented parameters, rich annotations and no output schema, the description covers the remaining gaps: what happens on test failure, that existing attachments persist, and the confirmation/secret-handling protocol. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters document their source (listAgents, agent_functions_list). The description only refers generically to 'the exact function, receptionist', adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Attach an existing Agent Function to one receptionist') plus the runtime effect ('so it can call it on live calls'). Clearly distinguishes itself from the create_code/create_http siblings because it says 'existing'.

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?

Implies this is the path for functions that already exist (contrasted with the create_* siblings) and gives the confirmation prerequisite before calling. It never explicitly says when to prefer creating a new function instead, so it sits just below the top mark.

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 non-read-only, non-destructive, non-idempotent, closed-world; the description adds real behavioral context on top: the code runs sandboxed, plan capacity is checked and returns upgrade_required when there is no room, and the function is only attached to a receptionist when all saved tests pass. That failure mode and the attachment gating are not derivable from the annotations or 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?

The purpose and scope are front-loaded and the guide pointer comes early, so the important routing information is not buried. It is slightly overstuffed, packing the alternatives, the confirmation workflow, and the required-field enumeration into one paragraph, but no sentence is pure filler.

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

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

For a 9-required-parameter mutation tool with deep nested objects (inputSchema children, codeTestCases with context/call) and no output schema, the description covers prerequisites, required inputs, capacity failure, attachment semantics and confirmation. The only gap is that it says little about what a successful call returns beyond the upgrade_required case, which is partly mitigated by the get_guide reference.

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

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

Schema description coverage is 100%, so the schema already explains every one of the 9 parameters. The description does add some meaning - that inputSchema is a root object whose children are the arguments, and that agentId attaches the function once tests pass - but it also restates the required-field list that the schema already enforces. This lands at the baseline for full coverage.

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 plus resource - 'Create a sandboxed Code function with saved tests' - and scopes it to 'logic the receptionist runs on live calls (calculations, lookups in fixed data)'. It also names the two sibling tools that handle adjacent cases, so an agent can distinguish this from create_http and update_code without opening any schema.

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

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

Explicit routing is given: 'To call an outside URL use agent_functions_create_http instead; to change an existing function use agent_functions_update_code', plus the prerequisite 'Read agent_functions_get_guide first for the main(input, context) contract'. It goes further and states the human-in-the-loop condition - enumerate the name, receptionist, behaviour, active state, language, code and test summary, then get explicit confirmation before calling.

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, readOnlyHint=false and idempotentHint=false, so the outbound-write nature is known; the description adds genuinely new behavior beyond that — background fire-and-forget mode for slow webhooks, same-step attachment via agentId, and a mandatory confirmation gate. The secret-header redaction rule ('never repeat secret header values') is a real operational constraint the schema does not convey. It does not describe the return value or what happens on duplicate creation.

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

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

Purpose is front-loaded and each subsequent clause carries distinct information: dispatch mode, attachment, confirmation workflow, secret handling. The confirmation clause is a crowded list ('function, receptionist, behaviour, active state, endpoint (HTTP) and code/test summary (Code)') but it is dense rather than 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?

No output schema exists, yet the description never says what a successful creation returns (function id, attached state). For a 10-parameter tool whose schema contains a nested inputSchema definition tree with children, validations and calculatedField, that structure is entirely undescribed. The workflow and safety guidance are solid; the data-shape guidance is the gap.

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

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

With 60% schema coverage, the schema already documents name, agentId, isActive, description, instruction and headers. The description adds semantic meaning for waitForResponse (background dispatch) and agentId (same-step attach) that the bare schema lacks. But the largest and most complex parameters — url, method, and the deeply nested inputSchema tree — get no explanatory treatment in either place.

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

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

The first clause pairs a specific verb with a specific resource — an HTTP/webhook Agent Function invoked by the receptionist on live calls — and the '(HTTP)' vs '(Code)' phrasing in the later sentence makes the split with agent_functions_create_code legible. An agent can tell this apart from the code-based sibling without opening either schema.

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

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

It gives concrete decision rules: use waitForResponse=false for slow webhooks, pass agentId to attach in the same step, and always show the full configuration and get explicit confirmation before calling. It stops short of an explicit 'use this instead of agent_functions_create_code when...' exclusion, so the alternative is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the definition is the 'full editable' one, it is a prerequisite for the update flow, and HTTP functions return no code. It does not discuss error behavior for an invalid ID, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with the core action and return contents, followed by the sequencing rule and the edge case. No redundant restatement of the name or title.

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

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

There is no output schema, but the description compensates by enumerating the returned fields, and it covers the prerequisite relationship and the HTTP-function edge case. For a single-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description adds provenance by pointing to agent_functions_list as the source of the ID, which helps the agent obtain a valid value.

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 one Code function's full editable definition by its ID') and enumerates exactly what is returned: name, description, instruction, active state, language, source, input schema and saved tests. It is clearly distinguishable from agent_functions_list, agent_functions_update_code and agent_functions_run_tests.

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 sequencing guidance ('Call it before agent_functions_update_code, which needs the complete definition back'), names the alternative for a narrower need ('to only check the tests use agent_functions_run_tests'), and states an exclusion ('HTTP functions have no code to read').

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, and destructiveHint=false, so 'Read-only' is redundant. What the description adds beyond the annotations is the ordering constraint (fetch the contract first) and the specific content of the response, which is what an agent needs to know before drafting a function. No token-size or caching caveats, 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?

Two sentences, both front-loaded: the return payload first, the call timing second. Every clause names a distinct piece of returned content; nothing is padding.

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

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

With no parameters, no output schema, and full annotation coverage, the only gaps an agent could have are 'what comes back' and 'when do I call it' — both are answered explicitly. The tool is a documentation fetch, and the description fully discharges that scope.

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 there is nothing to disambiguate; the baseline applies. The description correctly spends no words on parameter semantics and instead covers return content.

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

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

States a specific verb and resource ('Return the exact Code function contract') and then enumerates the payload: main(input, context), runtime context fields, sandbox limits, test-case shape, examples. That enumeration distinguishes it from the similarly named sibling agent_functions_get_code, which plausibly returns actual code rather than the spec.

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?

'Call before drafting or editing a Code function' gives an explicit trigger condition tied to the sibling workflows (create_code, update_code, create_http). It stops short of naming alternatives or stating when not to call it, so it is clear context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description nonetheless adds real substance: header values, secrets, and code source are omitted, telling the agent that returned summaries are redacted and that it cannot retrieve credentials through this tool.

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

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

Three short sentences, front-loaded with the resource and its subtypes, followed by the redaction caveat and the safety flag. No filler and nothing redundant with the annotations except the final 'Read-only' phrase.

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

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

Complete enough for a parameterless list tool with no output schema: the agent knows what is returned (summaries), what is withheld (secrets, headers, code), and that it is safe. Minor gaps remain around result ordering or whether all functions are returned in one response.

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

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

The tool takes zero parameters and the schema is an empty object with additionalProperties=false, so there is nothing for the description to clarify. Baseline 4 applies.

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

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

States a specific verb (List) and resource (Agent Functions), and enumerates the three concrete subtypes it covers: HTTP webhooks, connected MCP tools, and Code functions. It does not explicitly name the related get/create/update siblings, but the read/list scope is unambiguous.

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

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

Listing is implied as the discovery step before agent_functions_get_code or the create/update siblings, but the description never says when to use this versus those alternatives. Usage is inferable from the verb and sibling naming rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still earns credit for the non-obvious disclosure that execution is offline by default absent operator-granted network access. "Does not change the function" largely restates readOnlyHint but usefully confirms side-effect freedom for a tool that executes code.

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, action front-loaded, with the two most decision-relevant caveats (no mutation, offline) trailing economically. Nothing redundant enough to cut.

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, no-output-schema tool with rich annotations, the description covers action, side effects, and network posture adequately. It stops short of saying what a failing test or an unconfigured-sandbox response looks like, which would help an agent interpret results.

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

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

Schema coverage is 100% and the single functionId parameter is documented with a pointer to agent_functions_list, so the schema carries the load. The description only says "one Code function's saved tests" and adds no format or discovery detail beyond that.

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 ("Run one Code function's saved tests in the sandbox") plus the return shape ("return each result"), which cleanly separates it from siblings like agent_functions_get_code or agent_functions_create_code that touch code rather than execute tests.

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

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

Usage is implied (verify a saved function via its tests) but never spelled out as when-to-use versus an alternative, and no prerequisites such as needing saved tests to exist are stated. The only explicit guidance is the network condition, which is a constraint rather than a routing rule.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive behavior: all fields are required so it is a full overwrite, and proposed tests run first so a failing edit never replaces the current function. This test-gated atomicity is exactly the kind of context the agent cannot infer from the hint flags.

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 sentences, front-loaded with the replacement semantics, then the source-of-truth step, then the safety/confirmation gate. No restatement of the title or filler wording.

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

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

For a 9-parameter, fully-required tool with deeply nested schema and no output schema, the description covers the replacement model, the test gate and the confirmation requirement, which is sufficient to call it safely. It does not say what a successful response looks like, but with no output schema that is a minor gap given the strength of the rest.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds workflow-level meaning by stating every field is required and that the values should be seeded from agent_functions_get_code rather than authored from scratch. It also enumerates the fields to surface for confirmation (function name, receptionist, behaviour, active state, language, code and tests), which helps the agent fill the schema correctly.

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: "Replace one Code function (functionId from agent_functions_list) with a complete new definition." It names the exact identifier source and distinguishes itself from create_code and get_code by framing the operation as wholesale replacement of an existing function.

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 workflow guidance: start from agent_functions_get_code and change only what the user asked, plus an explicit gate — get confirmation before calling. It also names the sibling to read first, so the agent has both a when-to-use path and a prerequisite.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds substantive behavior beyond them: an account-level quota on custom tasks, a one-task-per-request rule, and a required user-approval gate 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?

Four short sentences, front-loaded with the core action, then the two mode branches, then the constraints, then the approval gate. No filler and no repetition of the tool name.

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

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

For a mutation tool with no output schema and only four flat, fully documented parameters, the description supplies everything an agent needs: both modes, quotas, per-request scope, and the approval prerequisite.

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% and the schema's own title description already spells out the standard-vs-custom conditional and the dependency on description/completionCriteria. The description restates that mapping rather than adding new meaning (e.g., format, length, or what happens if a custom title collides with a standard one).

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 ('Enable one call task on a receptionist') and immediately disambiguates the two modes: standard task from agent_tasks_list versus custom task. An agent can distinguish this from agent_tasks_list and agent_tasks_delete 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 branching instructions: pass only title for a standard task, pass title+description+completionCriteria for a custom task. It also states hard constraints (max 3 custom tasks per account, one task per user request) and a procedural precondition ('Get explicit approval before calling').

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 known. The description goes beyond them by stating the real-world effect (the live receptionist stops performing that task on calls) and prescribing a confirmation step — context the annotations cannot convey.

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

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

Three short sentences, front-loaded with what the tool does, then the risk disclosure, then the required pre-call behavior. Nothing is redundant or 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 two-parameter destructive tool with full annotations and no output schema, the description covers purpose, risk, and the confirmation protocol. It omits what happens on an unknown or already-deleted taskId (idempotency behavior), a minor but real gap for a delete operation.

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 taskId and agentId documented including their source endpoints, so the schema does the heavy lifting. The description only reiterates "by taskId" and adds no format, constraint, or edge-case detail beyond it.

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 and resource ("Remove one call task from a receptionist") and adds the keying parameter (taskId). It is trivially distinguishable from siblings agent_tasks_add and agent_tasks_list, which are the adjacent operations.

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

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

Provides clear operating context: this is a real mutation, and the caller must confirm with the user right before invoking. It doesn't explicitly name alternatives (e.g. agent_tasks_list to find the task first), though the schema's "Task ID from agent_tasks_list" cross-reference covers that routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read-only' in the description is redundant. What does add value is disclosing the response composition (current tasks, standard-task catalog, and remaining custom-task budget) in the absence of an output schema, hinting at a per-receptionist quota constraint.

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 waste: what it returns first, then the exclusion, then the safety profile. Front-loaded and scannable.

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

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

With no output schema, the description usefully covers the shape of the result. Minor gaps remain, such as whether the standard-task catalog is filtered by business type or how the budget is expressed numerically, but nothing essential for correct invocation 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?

Only one parameter (agentId) exists and schema coverage is 100%, with the schema itself explaining that the ID comes from listAgents. The description adds nothing about the identifier or its format, so the baseline 3 for high-coverage schemas applies.

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

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

States a specific verb (List) and resource (a receptionist's call tasks), then enumerates the three things returned: assigned tasks, the catalog of standard enableable tasks, and the remaining custom-task budget. The parenthetical '(what it collects or accomplishes on every call)' makes the resource concrete, and 'Read-only' separates it from the mutation siblings agent_tasks_add and agent_tasks_delete.

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

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

Provides one explicit exclusion ('Not for notification settings'), which steers the agent away from notification_settings_get, but gives no positive trigger condition or comparison against agent_tasks_add/agent_tasks_delete. Usage is only implied by the enumeration of returned content.

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 readOnly/non-destructive annotations, it discloses that summary and transcript are null or empty while analysis is pending or when the conversation is private, and that an unknown ID produces a not-found error. These are genuinely useful edge-case behaviors the agent could not infer from annotations, though it doesn't mention latency or size limits of the transcript payload.

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

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

Front-loaded with the core action and the returned fields, then the usage routing, then edge cases. It is somewhat dense with sibling names, but each clause carries information; nothing is pure filler.

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

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

An output schema exists, so the field enumeration is bonus rather than a necessity; combined with the null-state and not-found behavior, an agent has enough to call and interpret this correctly. Only minor gaps remain (e.g., whether the returned transcript is truncated for long calls).

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

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

Schema coverage is 100% and the schema itself already says the callId is a UUID, not a phone number. The description mainly reinforces that the ID comes from app_listCalls/getCallHistory, adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get one call by its UUID") and enumerates the payload it returns (caller/recipient, status, minutes, AI summary, transcript turns, webUrl). The sibling/alternatives (getCallDetails, getCallHistory, search) are named as different tools, so an agent can distinguish this from them 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?

Explicitly says to use it after app_listCalls or openCallsInbox returned the call id, and explicitly routes to getCallDetails for a shareable recording link and to getCallHistory/search to find a call first. Both when-to-use and when-to-use-something-else are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description adds real behavioral context beyond that: page ordering, cursor-driven pagination, and empty-result semantics. It stops short of anything about rate limits or result caps beyond the page size, but for a read-only list tool this is solid.

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 what the tool returns, then arguments, then pagination behavior, then alternatives — a sensible order with no filler sentences. It is dense and slightly overstuffed for one paragraph, but each clause carries information an agent would otherwise have to infer.

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

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

Given an output schema (so return values need not be explained), full annotation coverage, and 100% schema description coverage, the description supplies everything else an agent needs: ordering, pagination loop, empty-result meaning, and when to prefer a sibling tool.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the description mostly restates it (limit 1-50/default 25, direction values, query matching, cursor source). It adds little beyond the schema, and it introduces a real inconsistency by calling all arguments 'optional' while the schema marks all four as required — an agent could misread the contract from either side.

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

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

States a specific verb and resource ('List one page of calls'), its scope ('inbound and outbound merged'), ordering ('newest first'), and even the fields returned. It also names the sibling tools (getCallHistory, search) it is not, so an agent can separate it from app_getCall, getCallDetails, and getCallHistory 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?

Explicit routing guidance: use getCallHistory for a compact list, use search to find a call by name/phone/topic, and use this for the paged Calls inbox view. It also gives the operational rule for pagination ('when nextCursor is not null, pass it as cursor to get older calls') and the terminal condition (empty list = no match).

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

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

Goes beyond the annotations by stressing 'REAL ACTION, not a preview' — the event is written to the real calendar — plus the confirmation ritual, which the openWorldHint/readOnlyHint=false flags alone don't convey. It stops short of describing failure behavior when a slot has been taken or whether a retry creates a duplicate event.

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

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

Four short sentences, each doing distinct work: purpose, display obligations, anti-fabrication rule, and the real-action/confirmation warning. The critical mutation warning sits in the final, emphasized position 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 an 8-required-parameter real-world booking mutation with no output schema, the description covers the preconditions and confirmation workflow well. What's missing is what the agent should expect on success (booking id, event link) and what to do if the slot is no longer available.

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 88%, so the schema already documents nearly every parameter in detail, including the null semantics for guest fields and extraId. The description reinforces the no-invention rule for guest details but adds no syntax, format, or edge-case guidance beyond what is already in the property descriptions; 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 (Create one appointment) with the exact resource (in the user's connected calendar) and a hard precondition (at an exact slot returned by findCalendarSlots). This cleanly separates it from findCalendarSlots, cancelAppointment, and scheduleCall 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?

Explicitly names the upstream tool that produces the slot, mandates showing calendar/date/time/timezone/title/guest details, forbids inventing guest contact details, and requires explicit user confirmation immediately before the call. Both the when and the how are spelled out.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description adds useful behavioral context: content must be short facts, and the exact Q&A must be shown for explicit approval before calling. It does not cover duplicate handling or return behavior, but the annotation coverage lowers that burden.

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 and followed by scope exclusions and the approval requirement. Every sentence adds useful guidance with no 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 four-parameter create tool with no output schema and full schema coverage, the description provides the key content constraints and approval workflow. It is nearly complete, though it could mention duplicate handling or what happens after creation.

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%, and the schema already explains all four parameters in detail, including agentId/businessProfileId matching and default behavior. The description reinforces that the question and answer should be exact, but adds no parameter syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: add one custom question and answer to the Business Profile. It also distinguishes the tool from knowledge pages and call scenarios, so an agent can identify its role without opening the schema.

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

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

It explicitly limits use to short facts and names alternatives for documents and call workflows. It also adds a clear approval requirement before calling, leaving little ambiguity about when and how 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 carry destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable context beyond that: it stresses this is a REAL ACTION rather than a preview, and that the receptionist stops using the deleted Q&A — a downstream effect not encoded in any structured field. It stops short of stating reversibility or error 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 sentences, front-loaded with the operation and scope, then the destructive warning, then the confirmation workflow. 'Name the exact question' is mildly redundant with the confirmation sentence, but nothing is wasted.

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

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

For a destructive mutation with no output schema and fully documented parameters, the description covers what is destroyed, the downstream effect, and the required user-confirmation step. Missing only failure-mode detail (e.g. behavior when questionId no longer exists) which is minor.

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

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

Schema coverage is 100% and each of the three parameters (agentId, questionId, businessProfileId) has a detailed description including defaulting behavior and failure/retry guidance. The description only adds 'by questionId', so the schema does the heavy lifting and 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 (delete), the exact resource (one Business Profile question and its answer), and the keying parameter (questionId). This is clearly distinguishable from sibling business_qa_create/update/list without opening any schema.

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

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

Gives a clear precondition for use: 'Right before calling, show the user the exact change and get their explicit confirmation', plus the need to name the exact question. It does not explicitly route to alternatives (e.g. business_qa_update for edits instead of removal), so it falls short of a full 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 this a safe, idempotent, read-only, non-open-world operation, so the description does not need to restate safety. It adds real context beyond them: the returned items pair each question with its current answer and ID, and the ID is what feeds the create/update/delete siblings. It stops short of mentioning ordering, pagination, or what an empty profile looks like, which keeps it below 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 core action and its payoff (current answer plus ID) are front-loaded in the first sentence, and the remaining sentences are pure routing to the three relevant siblings. 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?

There is no output schema, so the description carries some of that load by naming the returned fields (question, current answer, ID), and the schema handles the identifier and failure paths. It is nearly complete for a simple listing tool, though an agent must still discover ordering and pagination behavior at call time.

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%, including the meaningful cases: agentId uses its attached profile and must match businessProfileId if both are supplied, an agent with no profile fails and should be fixed via updateAgent, and omitting both falls back to the default business. The description adds little parameter-level meaning of its own beyond noting that IDs come from this listing, so the baseline 3 applies.

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

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

The description states a specific verb and resource — 'List every Business Profile question with its current answer and ID' — and immediately defines what a question is (hours, services, pricing, location, policies). That level of detail lets an agent distinguish this from business_qa_list_profiles and knowledge_list_pages without opening any schema.

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

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

It gives explicit ordering guidance ('call it before business_qa_create, business_qa_update or business_qa_delete to see what exists and get the IDs') and routes two alternatives by condition: business_qa_list_profiles for multi-business workspaces, knowledge_list_pages for longer documents. Both the when and the when-not are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so "Read-only" in the description is largely redundant. The description does add genuine value by disclosing the response content (businesses plus their attached receptionists), but says nothing about volume, pagination, or ordering.

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, each earning its place: what it lists, why to call it, and its safety profile. The purpose and routing hint are front-loaded.

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

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

With no output schema, the description must convey what comes back, and it does at a high level (businesses and their receptionists). It leaves the exact field shape of a profile unspecified, which is a minor gap for an agent that needs to parse the result.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to explain. The description does signal that the output contains a businessProfileId usable elsewhere, which is a useful pointer beyond the 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 ("List the businesses (Business Profiles) on this account") and adds the nested content returned ("the receptionists attached to each"). This clearly distinguishes it from business_qa_list, which lists Q&A entries rather than profiles.

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 tells the agent when to reach for it: to obtain a businessProfileId for the business_qa_* tools, which names the downstream alternative family. It stops short of stating when it isn't needed (e.g., if the ID is already known), so not a full 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation/idempotency profile is covered. The description adds genuinely new behavioral context: an approval gate before invocation and a data-integrity rule ("Preserve exact numbers and policy facts"), which is exactly the kind of value-add expected when annotations are present.

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 waste: the operation, the integrity constraint, and the approval workflow, in that priority order. Nothing is repeated from the schema 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?

For a destructive, no-output-schema mutation with rich annotations and full schema coverage, the description supplies the two things structured fields can't: the approval requirement and the factual-precision constraint. It stops short of stating failure behavior (unknown questionId, mismatch between agentId and businessProfileId beyond what the schema says), leaving a small gap.

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

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

Schema description coverage is 100% and the per-parameter descriptions already explain questionId sourcing, agentId/businessProfileId fallback, and the answer format. The description's only added signal is "by questionId," which restates the schema rather than extending it, so baseline 3 applies.

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

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

States a specific verb and resource ("Replace the answer to one Business Profile question") and scopes it precisely by questionId, which cleanly separates it from business_qa_create/delete/list. It never names a sibling explicitly, so an agent must infer the boundary from the verb, but the operation itself is unambiguous.

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

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

"update each question separately" rules out batching and "Show the new answer and get explicit approval before calling" gives a concrete pre-call workflow. What's missing is guidance on when to use this versus business_qa_create (e.g. when the questionId doesn't exist yet), but the usage context is otherwise 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 readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' adds nothing; however, the description contributes real value by enumerating the returned fields and the 4-character ID format, which matters because there is no output schema. Minor gaps remain (no mention of behavior when no calendars are connected, or ordering).

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

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

Two sentences, verb front-loaded, no filler. The only near-redundancy is the trailing 'Read-only', which merely echoes the annotations and costs almost nothing.

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

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

With no output schema and no parameters, the description correctly compensates by listing exactly which booking settings come back, which is what an agent needs to decide to call it. It is slightly incomplete on edge cases (empty calendar list, ordering, whether IDs are stable across calls).

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The mention of '4-character calendar IDs' describes returned data rather than inputs, which is useful but not a parameter explanation.

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

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

States a specific verb and resource ('List every calendar connected to the receptionists') and enumerates the payload it returns (work hours, appointment length, buffer, timezone, double-booking, cancellation, 4-character IDs). This is clearly distinguishable from siblings like calendar_list_events, calendar_update_settings, and findCalendarSlots 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?

'Call first for any calendar question' gives an explicit entry-point rule that tells the agent when to reach for this tool before others. It stops short of naming the alternatives or stating exclusions (e.g., that event listing lives in calendar_list_events), so it is clear context rather than a full routing map.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description still adds real behavior: results aggregate across every connected calendar, and the date is interpreted in the owner's timezone with today as the default. It stops short of describing ordering, limits, or what fields come back per event.

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

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

Two sentences: the first front-loads what the tool returns and its scope, the second disambiguates against three siblings. No repeated annotation content and 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?

A one-parameter read tool with full schema coverage and a complete annotation set needs little more; the description covers scope, timezone, default, and sibling disambiguation. The absence of an output schema is minor for a simple event list.

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 would be 3, but the description adds the timezone interpretation of the date ('YYYY-MM-DD in the owner's timezone, default today'), which the schema's parameter text does not state. That is genuine meaning beyond the structured field.

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

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

States a specific verb and resource ('List the events already booked'), plus scope ('on one date ... across every connected calendar') and an answering use case. It is immediately distinguishable from findCalendarSlots, findAppointments, and calendar_list 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 findCalendarSlots for free times, findAppointments for appointments SkipCalls booked, and calendar_list for connected calendars. Both the when-to-use and the when-to-use-something-else conditions are 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses provider-specific rejections for Square, Calendly, TidyCal, Cal.com, and GoHighLevel, the fact that closeWorkDays removes stored hours, and the requirement to obtain explicit approval. These are meaningful behavioral constraints an agent could not infer from the annotations alone.

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

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

The purpose and required identifier are front-loaded, and each subsequent sentence carries a rule that prevents a concrete failure mode. The text is dense and packs several rules into long clauses, but little is genuinely 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 destructive 12-parameter mutation with no output schema, the description covers the critical gaps: approval, provider restrictions, partial-update behavior, and ambiguity handling. It does not describe the result of the call or what happens to omitted versus null fields, which is a minor remaining gap given the annotations and 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 100% schema coverage, the baseline is 3, but the description adds cross-parameter meaning the schema does not: workDays opens days while others are preserved, closeWorkDays closes exact days and strips stored hours, and ambiguous cutoff language must be resolved before setting workHoursByDay. It does not add much for straightforward fields like isActive or timezone, but the risky parameters are well explained.

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: "Change the booking settings of one connected calendar by calendarShortId." It is clearly distinguishable from siblings such as calendar_list, update_work, and updateTimezone because it scopes the action to a single calendar's booking configuration.

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 operational guidance: send only changed fields, use workDays only to open days, use closeWorkDays to close exact days, do not infer closeWorkDays from a partial list, and ask once about ambiguous until/close times. It also names when the tool cannot apply edits (provider-hosted calendars) and requires explicit approval before calling.

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 is a non-destructive, non-idempotent, closed-world write. The description adds real context beyond that: a PRO/Growth plan prerequisite, a ~6,000-character payload ceiling, and a mandatory human-approval protocol driving the confirmed flag. It stops short of saying what happens when the limit is exceeded or on duplicate creation, so it is strong but not exhaustive.

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

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

Purpose and scope are front-loaded in the first clause, then constraints and the approval workflow follow in the order an agent needs them. Dense but every sentence carries information; the semicolon-chained clauses make it slightly harder to scan than a fully structured version.

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-required-param mutation with no output schema, the description covers the operational essentials: plan gating, size limits, and the approval gate that governs confirmed. The remaining weakness is underspecified field semantics (notably isEnabled nullability and the title/agentId relationship).

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 17% — effectively just the confirmed field, which the description merely restates. It does add meaning for scenario ('step-by-step guide the receptionist follows') and whenToUse ('when it applies'), but title, agentId, and especially the nullable isEnabled semantics (what null means versus false) are left 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 (Create) and resource (one Call Scenario / Skill on a receptionist) and immediately defines the content of the object: when it applies plus a step-by-step guide. That clearly separates it from call_scenarios_update, call_scenarios_delete, and call_scenarios_reorder 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 sequencing and gating: check plan tier, call listCallScenarios first, show the exact change, wait for explicit approval, then set confirmed=true. It also tells the agent to keep one scenario focused and split unrelated flows, which is genuine usage guidance rather than restated purpose.

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, but the description adds material context beyond them: that this mutates the live receptionist rather than a draft ("REAL ACTION, not a preview"), that a specific confirmation protocol is required, and that PRO+ entitlement is needed. That is exactly the extra context annotations cannot express.

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 identity and the pause-alternative before the operational cautions, which is the right order. Slightly marred by restating the confirmation requirement twice ("show the exact change... wait for explicit approval" then "Right before calling, show the user the exact change and get their explicit confirmation") — defensible emphasis for a destructive op, but 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 3-parameter destructive tool with no output schema, everything an agent needs is present: entitlement check, the lookup call to run first, the human-approval gate, and the irreversible live-action warning. Nothing consequential is left to inference.

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

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

Schema description coverage is only 33% — only `confirmed` is documented in the schema, and the description's gating language reinforces its semantics well. However, `agentId` is required yet never explained in either place, and `scenarioId` is only named, not characterized. Partial compensation, not full.

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?

"Delete one Call Scenario by scenarioId" gives an unambiguous verb, resource, and lookup key, and immediately distinguishes itself from the two relevant siblings (call_scenarios_update for pausing, listCallScenarios for enumeration). An agent can place this tool in the family without reading 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?

Names the alternative explicitly (use call_scenarios_update with isEnabled=false to pause instead), states the prerequisite sequence (listCallScenarios first, show change, wait for approval, then set confirmed=true), and adds the plan-tier gate. When-to-use, when-not-to-use, and prerequisites are all present.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds what the annotations cannot: the plan gate, the mandatory user-approval protocol, and the fact that the destructive effect is limited to ordering (content is untouched) with scenarioIds interpreted top-first. That is real behavioral value beyond the structured fields.

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

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

Three short sentences, front-loaded with the action and ordering rule, followed by the plan gate and the approval protocol. No filler; every sentence constrains agent behavior.

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, no-output-schema mutation tool this covers action, ordering, permissions, and the approval safeguard. The remaining gap is whether scenarioIds is a full replacement list or a partial one, which matters for something marked destructive.

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

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

Schema description coverage is only 33% (only confirmed is documented), so the description must compensate. It does explain scenarioIds ordering semantics (top first) but leaves agentId entirely unexplained, and it never says whether the array must list all scenarios or what happens to omitted ones.

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

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

States a specific verb and resource: 'Set the order of a receptionist's Call Scenarios', and clarifies that scenarioIds is top-first. This clearly separates it from call_scenarios_create/delete and listCallScenarios, though it never explicitly distinguishes it from call_scenarios_update, which might also touch ordering.

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

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

Gives an explicit prerequisite workflow: call listCallScenarios first, show the exact change, wait for explicit approval, and only then set confirmed=true. It also names the plan requirement (PRO or Growth on older plans), so the agent knows when the call is even permitted.

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; the description adds genuinely new context, namely the paid-plan requirement, partial-update semantics, and an approval gate that explains why confirmed exists. It does not spell out what is lost or whether the change is reversible, so it stops short of the top score despite strong additions.

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

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

Three tight sentences; the mutation scope comes first, then the plan prerequisite, then the approval workflow. Nothing is redundant and the ordering matches the order an agent needs the 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 destructive mutation with no output schema, the description supplies everything that matters: prerequisites, the precondition call, the partial-update contract, and the confirmation requirement. Safety context comes from annotations, so no critical 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?

With schema description coverage at 14%, the description carries most of the load: it maps title, whenToUse, scenario (guide text), and isEnabled to their meanings and reinforces the confirmed gate. agentId is never explained and the null-means-unchanged convention is only implied by 'send only the fields that change', so a small gap remains.

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 (change) and resource (one Call Scenario) plus the exact mutable fields: title, when-to-use selector, guide text, enabled state, keyed by scenarioId. This clearly separates it from call_scenarios_create, delete, and reorder, which do different things to the same object.

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

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

Gives an explicit workflow: call listCallScenarios first, show the exact change, wait for explicit approval, then set confirmed=true. It also states the plan prerequisite (PRO or higher, Growth on older web plans) and the partial-update rule, so the agent knows both when to call it and what sequence to follow.

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, and the description goes well beyond them: it warns this is a REAL ACTION not a preview, states the change is irreversible ('cannot be undone automatically'), and mandates showing the user the exact change plus obtaining explicit confirmation first. That is exactly the operational context annotations cannot convey.

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

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

Front-loaded with the action, then the prerequisite, then the safety flow. Slight redundancy between 'Show the exact appointment, calendar, date, time, and timezone' and 'show the user the exact change and get their explicit confirmation,' which could be merged, keeping it from a 5.

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

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

With one 100%-documented parameter, rich annotations, and no output schema, the description covers sourcing, safety, and irreversibility well. It never indicates what the tool returns (cancellation confirmation, provider errors), which would be useful for a destructive one-param call with 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 100% and the single parameter is already documented as 'Exact tracked appointment ID returned by findAppointments.' The description reinforces exact-match sourcing but adds no format, validation, or failure semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Cancel one exact SkipCalls-tracked appointment at the calendar provider'), with a scope qualifier ('one exact') that distinguishes it from the sibling bulk/other-resource cancellers like cancelCall and cancel_reminder. An agent can route correctly 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 names the prerequisite source ('Use an appointment ID returned by findAppointments') and prescribes a confirmation workflow before invocation. It stops short of naming when-not-to-use cases or pointing to sibling tools for non-appointment cancellation, but the context is otherwise 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 mark it destructive and not read-only, but the description adds important behavior beyond them: it is a real action, not a preview, and the cancellation cannot be restored. It also prescribes a confirmation workflow, which is exactly the kind of context an agent needs for a destructive 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?

Three tight sentences with no waste. The purpose and scope are front-loaded, followed by parameter sourcing and then the irreversible-action 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 single-parameter destructive mutation with no output schema, the description covers the essential missing context: what it does, the prerequisite state, the irreversibility, and the required user confirmation. An agent has enough to call it correctly and safely.

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

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

Schema coverage is 100%, so the parameter is already documented, but the description adds useful source context by naming getCallHistory and scheduleCall as origins for the call id. The schema's warning that it is a UUID rather than a phone number or name is also reinforced by the description's focus on call id.

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

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

States a specific verb and resource: cancel a scheduled outbound call that has not been placed yet. The scope condition clearly distinguishes it from scheduling or inspecting calls, and the required call id origin points to related tools.

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

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

Gives clear context for when to use it: only for scheduled outbound calls not yet placed, and requires explicit user confirmation immediately before invocation. It does not explicitly name alternatives such as reporting an issue for already-placed calls, 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?

Beyond the destructiveHint annotation, the description explains the outcome: the reminder will not fire, the item is closed as handled, and it appears under the done view. That is meaningful behavioral context for 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 description is front-loaded with the core action and then adds only useful constraints and alternatives. Every sentence contributes to correct tool selection or invocation.

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

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

For a single-parameter destructive tool with no output schema, the description covers purpose, id source, outcome, and sibling alternatives. Nothing material is missing for correct use.

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%, and the description does not add syntax or format details beyond the schema's workItemId description. The baseline of 3 is appropriate because the schema already fully documents the single parameter.

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

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

The description specifies a clear verb and resource: cancel one pending reminder. It also scopes the action to reminders only and distinguishes sibling tools create_reminder and update_work, so an agent can select it confidently.

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

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

It states when to use this tool (a pending reminder the user no longer wants) and when not to use it (other Needs you items should use update_work). It also points to create_reminder when a new reminder is needed after cancellation.

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

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

Adds real context beyond the annotations: the note becomes visible on the contact page and in get_contact_timeline, existing notes are immutable, and the return payload {id, content, createdAt} is spelled out. The description does not cover permission/auth requirements or rate limits, and it does not explicitly say the write is additive-only vs. destructive, but the immutability statement largely covers that.

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

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

Front-loaded with the action and its purpose, then side-effect, then return value, then sibling routing in one compact paragraph. Slightly dense and the return-shape detail could be trimmed, but no sentence is filler.

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

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

For a two-parameter creation tool with no output schema, the description covers purpose, side effects and visibility, immutability of existing notes, return shape, and alternative tools. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description only loosely adds meaning by characterizing content as a remembered preference and pointing to where contactId comes from, which duplicates the schema's own note about using search (scope contacts).

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

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

States a specific verb+resource (add a new note to a contact's record) and clarifies what a note is with an example. It explicitly distinguishes itself from update_contact (contact fields) and create_reminder, so an agent can separate it from the closest siblings without reading schemas.

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

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

Gives explicit when-to-use ('a preference or detail the owner wants remembered'), when-not-to-use with named alternatives for both competing intents: update_contact for changing contact fields and create_reminder for reminders. Exclusions are concrete and route the agent correctly.

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 that this is a non-read-only, non-destructive, closed-world write. The description adds real context beyond that: the reminder surfaces under Later in Needs you, fires a notification with a SkipCalls chat ready to continue, and returns the reminder id plus fire time. It stops short of saying whether the chat is created at schedule time or fire time, which is the one behavior an agent might still guess at.

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

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

Four sentences, each doing distinct work: trigger, placement/notification behavior, return value, and sibling routing. Front-loaded with the trigger phrase. Slightly dense with three sibling references in one sentence, 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 5-required-param mutation with no output schema, the description covers the missing return-value information (id and fire time) and the user-visible effect of the call. Annotations carry the safety profile and the schema carries the parameters, so nothing an agent needs is absent.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail (including the null semantics for note and contactId, and the 9 PM–8 AM rule for timeNamed). The description adds only "at the given time" and does not enrich any parameter beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Create a reminder") plus the triggering user phrasing "remind me …", so an agent can match intent directly. It also distinguishes itself from create_contact_note, cancel_reminder, and update_work by name.

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

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

Gives explicit when-to-use (user says "remind me"), explicit when-not alternatives for two adjacent needs: cancellation routes to cancel_reminder, rescheduling to update_work (action later), and a note that should stay on a customer record routes to create_contact_note instead.

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

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

Annotations only say this is not read-only and not destructive; the description adds the material behavioral facts: the link is PUBLIC, it is scoped to a contact, it expires, and the agent is responsible for delivery. That public-exposure disclosure is exactly the kind of context annotations cannot convey. It stops short of saying how long the expiry is, whether the link is single-use, or whether generating a new link revokes an old one.

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 and its purpose, then the return value, then the operational caveat. No filler and nothing repeated from the schema.

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

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

For a one-parameter tool with no output schema, the definition covers purpose, the return value (URL and expiry), and who delivers the link. The remaining gap is link lifecycle detail – expiry duration and revocation behavior – which matters for a public, externally shared artifact but is not strictly needed to invoke the tool.

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

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

Schema coverage is 100%, and the schema already documents contactId as a UUID with a pointer to search (scope contacts) and a warning that it is not a phone number. The description adds nothing further about the parameter, so this is the baseline case where the schema does all the work.

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 ('Generate a public upload link for a contact') plus the file types it accepts, so the agent knows exactly what capability this exposes. It also implicitly carves out that delivery is the caller's job ('Send the URL ... yourself'), which separates it from sendSms, though it never names a sibling tool outright.

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 context of use is clear: a contact needs to attach files and the agent must hand them a link externally. The 'yourself' clause usefully signals that a separate messaging step is required, but there is no explicit when-not guidance (e.g. for existing files use list_customer_files) or stated prerequisites beyond the contactId.

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, idempotentHint=true and destructiveHint=false, so the safety profile is largely covered. The description adds genuinely non-structured context: the role/permission gate and plan tier required, plus the state effect of closing the assumption. It does not mention reversibility (e.g. estimates_undo) or what happens to the estimate afterwards, 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?

Three short sentences, zero filler: purpose first, alternative second, prerequisites last. Every clause carries actionable 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 one-parameter mutation with no output schema, the description covers the action, the alternative, and the permission/plan requirements. The only gap is what the agent should expect after confirmation — e.g. whether the accepted price becomes locked or can be undone.

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% and the single parameter businessProfileId is documented in the schema with its 'omit for the default business' semantics. The description adds nothing about it, so the baseline 3 for schema-covered parameters 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?

Uses a specific verb ('Accept') on a specific resource ('the open assumption shown by estimates_get') and states the resulting state change ('so it is closed'). It also names the sibling that performs the contrasting action, so an agent can distinguish it from estimates_update_prices and estimates_get immediately.

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 the condition for use (there is an open assumption to accept) and names the alternative path with the exact parameter needed ('use estimates_update_prices with answersAssumption=true'). It also lists prerequisites: owner or team admin, PRO plan and above.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: required access level (owner or team admin; PRO plan and above) and a preview of what the read returns (prices, open assumption, on/off flags). It does not mention rate limits or pagination, but for a single-object read that is minor.

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

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

Four short sentences, with the action front-loaded and the constraint/permission notes trailing. Efficient, though 'in plain words' and the double 'Essays/Estimates' phrasing are read twice before parsing cleanly.

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 compensates by enumerating the three things returned plus the access requirement and ordering hint. A single-optional-param read tool needs little more; only the return shape (structured object vs. text) remains unspecified.

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?

Only one parameter with 100% schema description coverage, so the schema already explains that businessProfileId should be omitted for the default business. The description adds nothing about the parameter; 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 (read) and concrete resources: Estimates prices, any open assumption, and whether Estimates and quoting-on-calls are enabled. That distinguishes it from the write-side siblings (estimates_update_prices, estimates_set_enabled), though it never names them explicitly and the phrase 'prices in plain words' is slightly awkward.

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?

'Call first' is an explicit sequencing instruction that tells the agent to hit this before the other estimates_* tools — genuinely actionable ordering guidance. It lacks an explicit 'use X instead when...' exclusion, so it stops short of a 5.

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

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

Annotations already declare this is an idempotent, non-destructive write. The description adds important context beyond annotations: prices are retained either way, and the caller must be an owner or team admin on PRO or above.

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 the action front-loaded and no wasted wording. The side-effect and permission details are compactly included.

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

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

For a simple toggle with complete schema coverage and annotations, the description supplies the key side effect and authorization requirements. No output schema exists, and none is needed for this operation.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description adds no parameter-specific syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource: turning Estimates on or off. It also distinguishes the action from sibling tools like estimates_update_prices by noting that prices are kept either way.

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 context for enabling or disabling Estimates and states the required role and plan level. It does not explicitly name alternatives or when not to use this tool, 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 this is a non-read-only, non-destructive, idempotent mutation, so the bar is lower. The description adds genuinely new behavioral context the annotations lack: the authorization role and plan tier required. It doesn't say what the receptionist actually does when quoting is off (refuse vs. deflect), which keeps it from a 5.

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

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

Two short sentences, zero waste, with the functional effect front-loaded and the access constraint following. Nothing is padded or repeated.

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

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

For a simple two-parameter toggle with full schema coverage, annotations, and no output schema, this is nearly sufficient — action, scope, and prerequisites are all present. The only real gap is disambiguation from estimates_set_enabled, which matters given how many estimates_* siblings exist.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description's 'allow or stop' phrasing merely mirrors the boolean 'enabled' semantics. Baseline 3 is appropriate — no syntax or edge-case detail is added beyond the schema.

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

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

States a specific verb pair ('Allow or stop') and a concrete resource ('the receptionist saying estimate prices to callers on calls'), making the effect unambiguous. However, it never distinguishes itself from the similarly named sibling estimates_set_enabled, leaving an agent to guess which switch governs what.

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

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

Provides clear gating context ('Owner or team admin; PRO and above') that tells the agent who can successfully call it. It stops short of naming an alternative or exclusion — notably estimates_set_enabled — so the selection guidance is incomplete rather than absent.

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

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

Annotations declare destructiveHint=true, but the description adds the details that actually matter: the Undo copy is destroyed too, the effect is permanent, and the agent is instructed to tell the user it cannot be undone before proceeding. Permission scoping (owner/team admin, PRO+) and the mandatory confirmation step are context the annotations do not carry.

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

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

Front-loaded with the destructive action and its irreversibility, with the confirmation requirement placed last as the immediate pre-call step. The warning is stated twice in close succession ('REAL ACTION, not a preview' and 'deleted for good; say it cannot be undone'), which is defensible emphasis for a destructive tool but slightly 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 one-parameter destructive tool with full annotation coverage and no output schema, this covers what an agent needs: what is deleted, who may do it, that it is irreversible, and the confirmation gate. Nothing required for a correct, safe invocation 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?

There is one parameter and the schema documents it at 100% coverage, including the 'omit for the default business' rule. The description never mentions businessProfileId, so it adds nothing beyond the schema — baseline 3 is appropriate here.

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 unusual precision: it deletes the Estimates prices *and their Undo copy*, which is what separates it from a plain price update or an undo. An agent reading only this line knows exactly what object is being cleared and what the resulting state is.

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 prerequisites (Owner or team admin; PRO and above) and an explicit pre-call workflow (show the exact change, get explicit confirmation). It also contrasts with a preview path via 'REAL ACTION, not a preview', implicitly routing away from the try/preview sibling, though it never names estimates_try, estimates_undo, or estimates_update_prices as 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 readOnlyHint/idempotent/non-destructive; the description adds beyond that by confirming the dry-run semantics ('Nothing is saved') and by disclosing role and plan gating (Owner or team admin; PRO and above). It does not cover edge behavior, e.g. what happens when no prices are configured for the account.

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 ordered action → safety → authorization, with zero filler. The terse 'Owner or team admin; PRO and above' fragment is compressed but still readable as a constraint.

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

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

For a two-parameter, fully described, annotation-covered read tool this is nearly sufficient: purpose, non-persistence, and authorization are all stated. The main gap is that with no output schema, the description could say what the returned estimate contains (e.g. price range or line items), which the agent currently cannot infer.

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

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

Schema description coverage is 100% and both parameters are documented there, so baseline 3 applies. The description reinforces the intent of 'text' by framing it as what a caller would say, but adds no syntax, length, or format guidance 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?

Names a specific verb and resource (show the estimate) and pins down the exact scenario: a simulated caller utterance priced against current prices. 'Nothing is saved' implicitly separates it from the persisted-estimate siblings (estimates_get), but no sibling is named, so differentiation is by implication rather than explicit routing.

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

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

Gives clear invocation context and hard prerequisites ('Owner or team admin; PRO and above') that an agent must check before calling. It never states exclusions or points at alternatives such as estimates_get or estimates_update_prices, so the when-not-to-use case is left to inference.

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

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

Goes well beyond the annotations by disclosing the single-level undo history, the no-op behavior with a clear message when no prior change exists, and the authorization/plan gates (owner or team admin; PRO and above). The annotations already flag destructive/non-idempotent, so those need no restating; what's missing is scope — whether it only reverses estimates_update_prices and leaves other estimate setting changes (e.g., set_quote_on_calls) untouched.

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

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

Front-loaded with the action, then the trigger, then edge-case behavior, then sibling routing and permissions — a logical order with no filler. The phrasing 'Put back the Estimates prices' is slightly awkward but does not cost comprehension.

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 with annotations and no output schema, this covers authorization, edge-case behavior, statefulness, and sibling routing well. Return shape and interaction with other estimate-mutating tools are the only unaddressed pieces, and neither is strictly required here.

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

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

Schema description coverage is 100% and businessProfileId is fully documented in the schema itself, including the multi-business case. The description adds nothing about the sole parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('put back the Estimates prices') and pins the exact scope: the state prior to the last estimates_update_prices call. The three sibling price tools (estimates_update_prices, estimates_start_over, estimates_undo) are cleanly separable from this sentence alone.

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

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

Gives an explicit trigger ('when the owner says the change was wrong, "undo that"') and names both alternatives with the condition that selects them: estimates_update_prices for a new change, estimates_start_over to delete all prices. The one-step limit also implicitly defines when this tool is not applicable.

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; the description adds the crucial fact that prior prices survive in estimates_undo, downgrading apparent risk, and states the authorization/plan requirement. It still does not say whether the change applies immediately or how partial or ambiguous input is handled.

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

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

Two sentences, no filler, with the core action and its input constraint front-loaded and the escape hatch and permissions trailing. Every clause carries information an agent needs.

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

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

For a destructive three-parameter mutation with no output schema, the definition supplies authorization, recoverability, and input format. What remains unstated is the effect model (does the supplied text replace or append to existing prices) and error behavior on ambiguous wording.

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

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

Schema coverage is 100% and the text parameter's description already spells out the verbatim, no-paraphrase rule with an example. The description's 'passed verbatim' phrasing reinforces that constraint but adds no new meaning for answersAssumption or businessProfileId, so the baseline 3 applies.

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

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

States a specific verb pair ('Change or add') and resource ('Estimates prices'), plus the defining constraint that the input is the owner's exact words. It also names estimates_undo as the counterpart, so an agent can separate this from the rollback sibling 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 concrete preconditions ('Owner or team admin; PRO and above') and points at estimates_undo as the recovery path, which implies when not to use this tool for restoring. It does not contrast against close siblings like estimates_try or estimates_confirm_assumption, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so 'this is read-only' is largely redundant. The description does add real scope information — it searches only appointments tracked by SkipCalls, not free/busy — but says nothing about result ordering, the 20-item cap behavior, or what happens when all-nullable filters are omitted. With annotations covering the safety profile, this is adequate but thin.

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

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

Two sentences, zero waste, with the primary capability front-loaded and the disambiguation trailing. Nothing repeats the schema or the annotations verbatim.

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 5-parameter search tool with no output schema, the description should clarify how filters interact (AND vs. OR across search/period/from/to) and what the result set looks like, since there is no output schema to fall back on. It covers the what and the not-what, but leaves the combination semantics and return shape 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 80%, so the schema carries most of the load, including the limit cap and the ISO-8601 offset requirement. The description names the searchable fields but adds no meaning for the undocumented 'period' enum (upcoming/past/all) and does not explain how search, period, from, and to combine or what a null value means for each of the five required-but-nullable parameters. Baseline 3 fits.

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 (find appointments tracked by SkipCalls) and enumerates the search dimensions: guest name, phone, email, title, period, and exact ISO date range. The closing clause ('does not search free time') separates it from the slot-finding sibling, 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 rules out two adjacent behaviors: searching free time (the findCalendarSlots territory) and changing calendar configuration (calendar_update_settings territory). That is clear routing context, though it stops short of naming the sibling tools or stating the 'when to use' condition positively (e.g., 'use when you need to look up an existing booking').

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context: the slots are real bookable availability from active connected calendars, and the returned calendar IDs, ISO starts, timezones, and provider resource IDs must be copied exactly into a booking proposal.

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

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

The description is three tightly written sentences. It front-loads the core purpose, then adds exclusions and downstream output handling without any wasted 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?

With annotations covering the safety profile and the schema fully documenting both parameters, the main remaining burden is return-value guidance because there is no output schema. The description partially handles this by naming the key returned fields to copy into a booking proposal, though it does not describe the full response shape or edge cases such as no availability.

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%, and the parameter descriptions already explain calendarShortId as an exact 4-character ID and date as a calendar-local YYYY-MM-DD value. The tool description adds little parameter-specific detail beyond referencing active connected calendars, so the schema carries the semantic load.

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

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

The description states a specific verb+resource: finding real bookable appointment slots in the user's active connected calendars. It also explicitly distinguishes this from existing-event lookup and calendar configuration, so an agent can tell it apart from siblings like findAppointments or calendar_update_settings.

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 clear usage context: use it for real bookable availability, not for existing-event lookup and not for calendar configuration. It does not name the alternative tools directly, but the exclusions provide enough routing guidance for an 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?

The description adds useful details beyond the read-only annotations: it lists the account fields returned and notes that billing is replaced by the SkipCalls dashboard link in ChatGPT. It does not describe auth requirements or rate limits, but it provides solid context for a read-only lookup 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 with the core purpose and then usage guidance. It is dense but every clause contributes relevant detail about the returned account fields, though the single long enumeration makes it slightly run-on.

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

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

With no output schema, the description carries the burden of explaining what is returned, and it does so thoroughly: business name, workspace ID, timezone, user vs owner, team size, receptionists, phone numbers, plan, and minute balance. That is complete enough for an agent to know what to expect.

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

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

The tool takes no parameters, so the baseline is 4. The description does not need to explain parameter behavior, and it correctly focuses on the returned account information instead.

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 ('Identify the connected SkipCalls account') and enumerates exactly what account details are returned. It is highly distinguishable from most siblings by its account-identity scope, though it does not explicitly name alternatives like getBillingInfo or getOverview.

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 clear usage context: 'Call when the user asks which account this is or before account-wide work.' It does not, however, state when not to use it or route to sibling tools such as getBillingInfo for billing-specific questions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context about the default compact Markdown response and why JSON should be reserved for exact editable fields, though it does not cover error behavior or missing-agent handling.

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 tightly written sentences with the main purpose front-loaded and the format guidance following immediately. No wasted text.

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

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

For a read-only getter with two fully documented parameters and no output schema, the description is complete enough: it names the returned information categories and explains the response-format choice.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the format tradeoff but adds little beyond the schema's own format description, and the stated default slightly conflicts with format being a required parameter.

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

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

States a specific verb and resource: get rich detailed receptionist info, and enumerates the included areas (config, instructions, resources, knowledge, stats). This clearly distinguishes it from listAgents and updateAgent.

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

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

Provides clear guidance on when to use format="json" versus the default Markdown, but does not explicitly say when to choose getAgent over siblings like listAgents, getOverview, or updateAgent. Usage is implied by 'rich detailed' rather than stated as a selection rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real beyond-schema behavior: it is a read-only enumeration returning a compact table with display name, id, style tags, current receptionist usage, and a preview link, plus the constraint that only the exact id may be forwarded.

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

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

Two sentences, both load-bearing: the first defines output contents, the second defines the downstream contract. No filler and no restatement of the tool name.

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

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

There is no output schema, so the description's enumeration of returned fields carries that burden and does so adequately for a zero-parameter list. With annotations covering the safety profile, nothing material is missing for correct invocation.

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

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

Zero parameters, so the baseline is 4; there is nothing to disambiguate. The only 'parameter' guidance concerns the downstream updateAgent `voice` field, and the description correctly warns to pass the exact id rather than a display name.

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

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

States a specific verb+resource ('List voices the user can select for a receptionist') and enumerates the exact columns returned. This clearly separates it from mutation siblings like updateAgent and list siblings dealing with calls, contacts, or agents.

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 downstream: 'Pass only the exact id to updateAgent `voice`' tells the agent this is the discovery step before an update. It gives clear context but does not state exclusions or when another voice source would be preferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only' is largely redundant. However the description adds real behavioral context beyond the annotations: output depends on which client is calling, and in ChatGPT the payload is deliberately reduced to a link rather than billing data. That is the kind of non-obvious trait annotations cannot convey.

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

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

Three tight sentences with the client-conditional behavior front-loaded and the exclusion list stated up front. Minor redundancy in repeating 'Read-only' against the annotations, but no padding.

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 compensates by describing what is returned in each client context (dashboard link vs. subscription status, minute balance, account limits). For a zero-parameter read tool this is close to complete; it does not describe the link format or whether balance values are formatted, but that is minor.

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

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

The tool has zero parameters and the schema has additionalProperties=false, so there is nothing to explain; baseline 4 applies. The description correctly asks for no 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 states a specific resource (billing info: dashboard link, subscription status, minute balance, account limits) and preconditionally forks behavior by client type, which is genuinely informative. It implicitly distinguishes itself from startSubscriptionCheckout by saying it does not include checkout, though the sibling is not named explicitly.

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

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

It clearly gives the condition that selects each behavior: ChatGPT clients get the dashboard link, other MCP clients get subscription data. There is no explicit 'use X instead' routing to a sibling, but the exclusion of plans/prices/checkout implies where checkout belongs (startSubscriptionCheckout).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral detail: the response includes a signed public share link to the call page, which is a shareable artifact the agent should know about before surfacing it. Minor gaps remain (behavior when the UUID is invalid, transcript size/truncation).

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

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

Two sentences, front-loaded with the core action, and the routing sentence sits at the end where it belongs. The return-field enumeration is long but earns its place because no output schema exists; the only cost is that the first sentence is a dense run-on.

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 one parameter, no output schema, and no nested objects, the description carries the right load by describing the response shape in prose. It stops just short of full completeness because it says nothing about failure modes for an unknown UUID or whether the transcript is truncated.

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

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

Schema coverage is 100% and the single callId parameter is already documented as a UUID from getCallHistory or search, not a phone number. The description reinforces that provenance but adds no new syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Get everything about one call by its UUID") and then enumerates exactly what comes back: status, time, receptionist, AI summary, transcript, and a signed share link. The inbound/outbound auto-detection is called out, which distinguishes it from tools that require a direction or phone number.

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 sequences the tool: "Use it after getCallHistory, search or get_contact_timeline gave you the call id." It also names the alternatives and their selecting conditions — getCallHistory to list calls, search to find one by name, phone or topic — so an agent can route without guessing.

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/destructive/openWorld, so the bar is lower, and the description still adds real behavior: results are compact, the hard time boundary semantics, future scheduled outbound calls are excluded, and which fields come back. It does not mention auth requirements, rate limits, or ordering, so not a 5.

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

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

Front-loaded with purpose, then params, then boundary rules, then the handoff to getCallDetails; nearly every clause carries an actionable constraint. The enumeration of return fields is slightly list-like and the density of clauses makes it a bit heavy, but nothing is truly wasted given there is no output schema.

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

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

With no output schema, the description compensates by naming the returned fields; with four required params, all are discussed; and the sibling handoff (exact Call ID into getCallDetails) closes the loop. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so a 3 would be the floor, but the description adds cross-cutting semantics the schema does not: time windows must be expressed via sinceHours rather than other filters, and count should be the smallest useful value with more only when needed. That is genuine meaning beyond the per-parameter descriptions.

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

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

States a specific verb and resource ('Compact list of the user's calls') and implicitly contrasts with getCallDetails by telling the agent to fetch one full call afterward. It does not distinguish itself from nearby look-alikes such as app_listCalls or search, which is the only thing keeping it from a 5.

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

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

Gives explicit selection rules: use sinceHours for any explicit time window, and that window takes precedence over name/phone/company/topic filters. It also states a hard negative ('do not silently search older calls when that window has no match') and the escalation path (increase count or paginate inside the boundary), so an agent knows both when to use it and when not to widen.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: results are 'verified' carrier-specific codes or portal steps, and the user's number is injected so the agent needn't construct it. It stops short of saying what happens for an unrecognized carrier or in what shape the steps come back.

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

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

Two sentences with no padding: the first front-loads what the tool returns, the second front-loads the interaction prerequisites. Every clause carries actionable 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 two-parameter read-only lookup with no output schema, the description covers what is produced (codes or portal steps), that the number is filled in, and the conversational setup required. Minor gaps remain around unknown-carrier behavior and how the missed/all-calls choice is communicated to the tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description reinforces that the carrier is captured in the user's own words and that the target number is the user's SkipCalls number. However, it instructs the agent to capture a missed/conditional versus all-calls choice that has no corresponding parameter, leaving the agent unsure how that decision reaches the tool.

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

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

States a specific verb (Get) and a specific resource (verified carrier-specific call-forwarding codes or portal steps), plus the key qualifier that the user's SkipCalls number is pre-filled. This is distinguishable at a glance from siblings like runForwardingTestCall or transfer_numbers_list, which also touch forwarding.

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

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

Gives an explicit precondition sequence: ask the user to name or confirm the carrier and to choose missed/conditional versus all calls before invoking. It does not name an alternative tool or state when not to use this one, but the preconditions are clear enough that an agent knows how to reach the call correctly.

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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: the timeline is capped at the 5 newest events, and an unknown or deleted ID yields {error: "Contact not found"}. It does not discuss auth or permissions, but for a read-only single-record fetch that is a minor gap.

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

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

The purpose and the alternative are front-loaded, and the field enumeration earns its length by telling the agent what it will receive. The parenthetical naming of "Skip AI (bypassReceptionist)" is slightly cluttered but still informative.

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

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

There is no output schema, so the description carries the burden of describing returns — it lists the returned fields, the timeline cap, and the not-found error shape. Combined with the usage routing to get_contact_timeline, nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100% and the contactId description already says to obtain the UUID from search and that it is not a phone number. The description's "(scope contacts, by name or phone)" restates that guidance rather than adding meaning, so it sits at the baseline for a fully documented single parameter.

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

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

States a specific verb and resource ("Get one contact by ID") and immediately enumerates the record contents, so the agent knows exactly what comes back. It also distinguishes itself from the two nearest siblings, search and get_contact_timeline, without needing to open either schema.

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

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

Gives an explicit precondition ("use it after search (scope contacts, by name or phone)") and an explicit alternative for the richer case ("for more history use get_contact_timeline"). Both the when and the when-not are named.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the remaining burden is modest, and the description does add ordering ('newest first'), an event field list, and the unknown/deleted-ID error. It does not disclose pagination beyond the stated 50-event ceiling or whether results are truncated silently.

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 capability and scope come first, then the event inventory, then sibling routing, then the error case — a well front-loaded structure with no filler sentences. Dense but every clause carries information an agent would otherwise have to infer.

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 compensates by naming the per-event fields (id, type, date, title, summary, metadata) and the error shape. Combined with the annotations and full schema coverage, nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the schema already explains the 1-50 limit, the default of 20, the unreachability of older events, and that contactId is a UUID rather than a phone number. The description adds no parameter-level meaning beyond reinforcing 'newest first' ordering, 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?

States a specific verb and resource ('Get one contact's full interaction history') and enumerates exactly what is included: calls, SMS, jobs, follow-ups, appointments, notes, document uploads and field changes. It also names the sibling tools it is not (get_contact, getCallDetails, getTextConversation), so the 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?

Gives an explicit decision rule ('what happened with this customer') and then routes three common alternatives to their own tools with the condition that selects each. It also states the failure case ({error: "Contact not found"} for unknown or deleted IDs), which is the kind of edge guidance agents need before calling.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the content is static, it is idempotent enough to call once per session, and it explicitly does not expose the chat system prompt, persona, or user data — a useful disclosure about what will and will not be 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?

The imperative "REQUIRED READING" is front-loaded, followed by scope, then contents, then timing, then exclusions — a sensible priority order. The single sentence groups four clauses and runs long, but each clause carries distinct information an agent needs.

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

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

For a zero-parameter, read-only, closed-world info tool with no output schema, the description fully covers what it returns, when to call it, and what it withholds. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly says nothing about inputs, which is right for a no-arg orientation endpoint, and its content summary substitutes for what a parameter list would normally convey.

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 ("Returns a static overview of what SkipCalls is") and enumerates the exact contents: product structure, tool-routing guidance, and editing rules. It is unmistakably distinct from every sibling tool in the list, none of which is a documentation/orientation endpoint.

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 timing instruction: "Call this once at the start of a session before touching any other tool," plus "REQUIRED READING for any external assistant connecting over MCP." This is an unambiguous when-to-use directive with an implicit exclusion (once, not repeatedly).

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 meaningful behavior beyond the readOnly and non-destructive annotations by stating that reading does not mark the thread as read or change anything. It also explains cursor-driven pagination, though it does not discuss permission requirements or error 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 compact, front-loaded with the core action, and contains no wasted wording. Every sentence contributes either purpose, prerequisite, or pagination behavior.

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

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

For a read-only, paginated retrieval tool with no output schema, the description gives enough context to invoke it correctly. It covers the source of conversationId, the first-page cursor value, and how to continue paging.

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 100%, so the schema documents the parameters well. The description still adds useful semantics by tying cursor behavior to page progression and reinforcing that conversationId is not a phone number, email, or customer name.

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: reading messages of one SMS, email, or website-chat thread. It clearly distinguishes this tool from listTextConversations and search, and states its pagination scope of up to 10 messages per page.

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 tells the agent to obtain conversationId from listTextConversations or search first. It also gives precise pagination guidance: pass cursor null for the first page, and reuse the exact returned cursor when more messages exist.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, and the description is consistent with them. It goes further by enumerating what the read returns (valuable since there is no output schema) and by flagging that downstream actions require user confirmation.

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, front-loaded sentences with no filler; the read scope and the field list come first, and the routing sentence comes last. The field list is a dense comma run, but every item conveys returned data an agent needs.

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

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

With no output schema, the description carries the burden of describing the response, and it does so by naming the fields returned. Combined with the read-only framing and next-step routing, an agent has enough to call it and know what comes back, though paging/error behavior is unmentioned.

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?

Only one parameter and schema description coverage is 100%, with the schema already specifying "Exact item id returned by listWork or getWork." The description adds no syntax, format, or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and scope ("Read one Needs you item") plus the concrete payload the item carries: customer, action, prepared text/recipient, quotes, calls, texts, due date. The singular "one" implicitly separates it from the list_work sibling, and the field enumeration makes the resource unmistakable.

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 post-read activity to sendSms or scheduleCall and then update_work, with the "user confirmation" precondition stated. It gives clear context for acting but never states when to use this versus browsing with list_work, so the read-side routing is left implicit.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description only needs to add operational context — and it does: this is a human-in-the-loop write gated on owner approval of the exact text. It does not say what happens on a duplicate title or what the call 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?

Three short sentences, front-loaded with the core action and approval gate, then the exclusion. No filler and nothing repeated from the schema 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?

For a 3-parameter mutation with no output schema, the description covers the essential thing an agent could get wrong: calling before owner approval. Remaining gaps are the post-call outcome (created page identity, duplicate handling), which are minor for a straightforward create.

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%: title and content have no field descriptions, and only confirmed is documented. The description partially compensates by requiring the "exact title and complete text" — implying full-fidelity, non-truncated content — but adds nothing about title uniqueness, length limits, or content format.

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 one Knowledge Base text page") with an explicit scope ("one") and audience ("the receptionist can cite on calls"). The closing "Does not upload files" actively separates it from file-oriented siblings like create_upload_link and list_customer_files.

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

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

Gives a concrete precondition workflow: show the exact title and full text, obtain explicit approval, then call with confirmed=true. The "does not upload files" clause adds a negative case. It stops short of naming knowledge_update_page or knowledge_get_page as the alternative path, so routing is implied 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the return payload (full text and timestamp) and the workflow constraint about reading before editing. It does not say what happens with an unknown or stale ID, which is the remaining gap.

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 sentence with the primary action front-loaded, followed by the update-ordering constraint and the disambiguation pointer. 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?

No output schema exists, but the description compensates by naming the returned content precisely. For a one-parameter read tool with full annotation coverage, nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and the single parameter is self-documenting, so the baseline is 3. The description adds provenance the schema only hints at: the ID must come from knowledge_list_pages, indicating it is opaque rather than guessable.

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: reading the complete text plus last-updated timestamp of a single Knowledge Base text page, keyed by ID. It distinguishes itself from knowledge_update_page and from search-based discovery in the same sentence.

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

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

Explicitly says to read before knowledge_update_page so the edit preserves existing text, and routes the agent to search with scope knowledge when the goal is finding which page mentions something. It also names knowledge_list_pages as the source of the ID, so when/when-not guidance is complete.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioural facts: the response omits page bodies, the set is limited to text pages, and uploaded files are managed in the app and absent from results. It stops short of stating ordering or any cap on the returned list.

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

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

Three compact sentences with no waste: capability and return shape first, then when to use and what to use instead, then the exclusion plus the reason. The parenthetical defining what a page is earns its place by distinguishing pages from uploaded files.

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

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

There is no output schema, yet the description already specifies the returned fields (ID and title) and what is omitted (body text), which is the key information an agent needs to plan a follow-up call. Combined with the sibling routing, nothing material is missing for a zero-argument list tool.

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

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

Zero parameters, so the baseline is 4; the description correctly implies an unfiltered, complete enumeration rather than hinting at filters that do not exist. Nothing further is needed for a no-arg tool.

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

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

Opens with a specific verb+resource ("List every Knowledge Base text page") and immediately scopes the return shape ("with its ID and title, no body text"). It also disambiguates from the two nearest neighbours: `search` with scope knowledge and the uploaded files that are not listed here.

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 three explicit uses (fetch an ID for knowledge_get_page / knowledge_update_page, or check existence before knowledge_create_page) and names the alternative for content search. No inference is required to pick between this and `search`.

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