Make Agent Fast

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

Annotations already declare non-readOnly, non-idempotent, open-world behaviour, so the bar is lower, and the description adds genuinely new context: text is ingested synchronously while a URL is crawled in the background over 'a minute or two'. That async distinction is the single most important operational fact here and it is not recoverable from the annotations. It stops short of saying what happens if the crawl fails or whether re-adding replaces existing knowledge.

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 waste, front-loading the purpose and then the behavioural difference between the two modes. The example payload types (prices, opening hours, policies) earn their place by clarifying what 'knowledge' means.

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

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

For a non-idempotent write tool with no output schema and full schema coverage, the description covers purpose, input modes and the sync/async timing that an agent must know before calling. It omits whether the call replaces or appends existing knowledge and what a successful background crawl returns, which would matter for a mutation call.

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

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

Schema coverage is 100%, so every parameter including url, text, title, agent_id and max_pages is already documented, which sets the baseline at 3. The description reinforces the url/text mutual exclusivity and the max_pages scoping, but adds no format, limit, or expectation beyond the schema's own text.

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

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

A specific verb + resource: 'teach an agent' from a URL or from supplied text, which makes the two supported input modes immediately clear. It does not name or distinguish itself from the closer siblings (create_agent_from_website, create_agent_from_notes), leaving the agent to infer that this adds knowledge to an existing agent rather than creating one.

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

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

Usage is only implied: the description explains the two input forms and their timing, from which an agent can infer when to pick this over the create_* siblings. There is no explicit 'use when' statement, no exclusion of alternatives, and no stated prerequisite such as the agent already existing.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), yet the description adds genuinely non-obvious behavior: the build is asynchronous (~1 minute), the result is a draft with the website widget deliberately off, and the response carries agent_id, build status and dashboard URL. The one notable omission is that idempotentHint=false — repeat calls create duplicates — is never warned about.

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: purpose and scope first, then the return payload, then the async/build-state caveat. Every sentence carries distinct information and 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 output schema, the description correctly shoulders the burden of explaining the return values and does so. It also covers the async lifecycle and widget-off default. Only the duplicate-creation consequence of non-idempotency is left out.

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

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

Schema description coverage is 100%, so all three parameters (including the business_notes length bound and the language enum) are already documented. The description's list of facts (prices, hours, location, delivery, ordering) largely restates the business_notes schema text, adding reinforcement rather than new meaning; 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 new draft agent") and narrows the scope with "for a business without a website, from a few written facts," which cleanly separates it from the create_agent_from_website sibling without naming it. The parenthetical enumeration of what the notes should contain makes the input target unambiguous.

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

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

The phrase "for a business without a website" gives a clear implicit selection rule against create_agent_from_website, and "draft agent" signals the follow-up path (set_website_widget, add_knowledge). It stops short of explicitly naming the alternative tool or stating prerequisites, so it is a strong context signal rather than a full when/when-not statement.

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 that the agent is created in draft state, the build runs asynchronously for about a minute, the chat widget remains off, and the response includes agent_id, build status and dashboard URL. openWorldHint and non-idempotency are consistent with the described website-fetching write 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 sentences, front-loaded with the action, then the return/timing, then the alternative path. Every sentence carries distinct information with no repetition of 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?

With no output schema, the description supplies the essential return fields and the async completion window, plus the draft/widget state that an agent needs to avoid immediately testing or chatting. Nothing material 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 schema documents both website_url and the language enum with its default, so the description need not restate them. The description adds nothing about parameter semantics beyond the generic mention of reading a website; 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 new draft agent by reading a business website') and names the sibling it is not for cases without a website. An agent can distinguish it from create_agent_from_notes 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?

Explicitly routes the agent: use this when a business website exists, use create_agent_from_notes when it does not. The condition that selects the alternative is stated, not inferred.

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

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

Annotations already establish that this is a safe, read-only, idempotent, non-destructive operation with a closed-world scope. The description adds useful detail about returned content, but does not add operational behavior such as auth requirements, rate limits, not-found handling, or response shape beyond the enumerated 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?

It is front-loaded with the core action and stays to one sentence with no filler. The enumeration of channels and returned artifacts is long but each item conveys specific value, though the channel list is slightly verbose for a description.

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 a simple one-parameter read-only schema and comprehensive annotations, the description is nearly complete for invocation. It compensates for the absence of an output schema by enumerating expected return fields, though it lacks error/empty-state or pagination-style guidance.

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 sole agent_id parameter is fully documented in the schema as coming from list_agents. The description does not add parameter syntax, constraints, or source guidance beyond what the schema already provides, so the baseline applies.

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

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

The description uses a specific verb and resource: "Show one agent," then enumerates the exact details returned, including widget status, build progress, channels, install code, knowledge sources, and latest knowledge-add result. This clearly distinguishes it from list_agents and from mutation siblings like add_knowledge or set_website_widget.

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 single-agent lookup context is clear, but the description gives no explicit when-to-use/when-not guidance or alternative routing. It relies on the reader to infer that list_agents is the way to discover agent_id and that other getters cover conversations or reports.

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 closed-world scope, so the safety profile is covered. The description adds genuine behavioral value by describing what the transcript contains (failed answers, your sent replies), which is return-content context the annotations do not provide. It stops short of mentioning auth requirements, pagination, or behavior for missing/invalid IDs.

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 well-formed sentence with the core action front-loaded and zero filler. The enumeration of transcript contents is compact and 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?

For a two-parameter, fully-annotated, read-only tool, the description is largely complete: it conveys the read-only safety profile, the scoping to one conversation, and the shape of the returned transcript, which partially compensates for the absence of an output schema. Minor gaps remain around pagination/size and error behavior for unknown IDs.

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

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

Schema description coverage is 100% and both parameters are documented with their provenance (agent_id from list_agents, conversation_id from list_conversations). The description adds no additional parameter meaning, 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 ('Read') and resource ('one conversation's transcript') and enumerates the content types returned. It implicitly distinguishes itself from list_conversations by being single-conversation scoped, but never names or contrasts any sibling explicitly.

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

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

Usage is implied: read it to see what the customer wrote, what the agent answered, which answers failed, and your own replies. There is no explicit guidance on when to prefer this over list_conversations or list_unanswered_questions, and no exclusions or prerequisites 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, openWorldHint=false and non-destructive, so safety is covered. The description adds genuine behavioral context by naming the three fixed reporting windows and the exact contents of the report — valuable given there is no output schema. It stops short of saying whether figures are aggregates vs. per-period breakdowns.

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

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

One sentence, front-loaded with the purpose, then a compact colon-delimited list of outputs. Nothing is padded and no clause needs to be re-read.

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, closed-world, two-parameter report tool with full schema coverage and no output schema, the definition covers purpose, windows and the metric set. The remaining gap is the shape of the response — whether metrics are single totals or broken down per period/channel — which an agent must discover 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 coverage is 100%: both params are described, the days enum with its default is spelled out, and agent_id points at list_agents. The description's mention of '7, 30 or 90 days' merely echoes the enum, adding no format or fallback semantics, 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 ('Summarize') plus resource ('how an agent performed') and then enumerates the exact metrics returned: conversations by channel, leads, bookings, handoffs, top questions, unanswered count. That enumeration effectively separates it from sibling list tools like list_leads or list_unanswered_questions, which return raw rows rather than an aggregate report.

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 implies the usage context (periodic performance review over 7/30/90 days) but never says when to pick this over get_agent or the list_* siblings, nor any exclusions or prerequisites beyond the schema's reference to list_agents for the ID. Usage is inferable but not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context: results are scoped to one connected company (no cross-tenant querying) and include the widget on/off flag, which is the field an agent would otherwise have to discover empirically.

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 well-formed sentence that front-loads the resource and scope, then lists return fields. No filler, no repetition of the 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?

With no output schema, the description correctly compensates by naming the returned fields, which is what an agent needs to plan downstream calls. Minor gaps: no mention of ordering, result size, or whether inactive/archived agents are included.

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 additionalProperties is false, so there is no parameter semantics to explain; baseline 4 applies. The description's mention of returned fields is a bonus rather than a substitute for parameter docs.

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 (AI customer-service agents) scoped to the connected Make Agent Fast company, and even names the fields returned (agent_id, name, widget status). This clearly separates it from the singular get_agent and from list_conversations/list_leads without needing 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?

Usage is implied rather than stated: an agent can infer this is the discovery step before get_agent or set_website_widget, but the description never says when to prefer it over those siblings or what it excludes. For a zero-parameter enumeration tool this is adequate but leaves routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful behavior (result ordering 'newest first') but says nothing about result volume, default page size, or pagination behavior, which is the main thing an agent would want to know here.

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

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

Two sentences, zero filler, with the resource and ordering front-loaded before the filter options. Every clause maps to a real capability of the tool.

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

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

The tool has six parameters, no output schema, and a pagination cursor, yet the description never mentions paging or what a returned conversation contains. Adequate for identification, but thin for actually driving the call correctly on a multi-page listing.

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 83%, so the schema carries most of the load and baseline 3 applies. The description mentions the channel, unanswered, and text filters but adds no precision beyond the schema — in fact the schema's only_unanswered description ('website and voice conversations where the agent failed to answer at least once') is more exact than the prose. limit, cursor, and agent_id are never mentioned.

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 recent customer conversations') plus the scope (website widget, voice, messaging channels) and ordering ('newest first'), which separates it from the singular get_conversation. It does not explicitly name the sibling tools it should be preferred over, so it stops short of a 5.

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

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

The second sentence hints at narrowing by channel, unanswered status, or text, which implies use cases but never states when to choose this over get_conversation, list_unanswered_questions, or list_leads. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful behavior (newest-first ordering, per-agent scoping, the fields returned) but says nothing about pagination, default page size, or result caps.

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

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

One tight sentence, front-loaded with the verb and resource, with the return shape and ordering packed into a parenthetical. 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?

There is no output schema, and the description partly compensates by naming returned fields and ordering. But for a 3-parameter tool with 33% schema coverage, the undocumented 'only_qualified' flag and the pagination/limit behavior are real gaps that leave the agent guessing.

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% — only agent_id carries a description (pointing at list_agents). The description does not explain the other two parameters: 'limit' (default 20, max 50) and especially 'only_qualified', whose meaning is never defined anywhere.

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

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

Specific verb (list) plus resource (leads) and even names the returned fields (name, email, what they asked) and ordering (newest first). It is clearly distinct from update_lead, but it never explicitly contrasts itself with siblings such as list_conversations or list_unanswered_questions.

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

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

No when-to-use or when-not guidance is given; the only routing hint is the schema note that agent_id comes from list_agents. Nothing tells the agent when to reach for list_leads versus list_conversations or get_report.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context about ordering and counts, but does not cover pagination, rate limits, or response format details. A 3 is appropriate given the annotations carry the safety profile.

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

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

A single front-loaded sentence that packs purpose, ordering, and return information with zero waste. Well-structured and efficient.

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

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

For a simple read-only list tool with annotations covering safety, the description provides enough context about what is returned. The missing explanation of the limit parameter is a minor gap, but overall the definition is nearly complete.

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

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

Schema description coverage is 67%: days and agent_id are documented, but limit has no description beyond min/max/default. The tool description does not mention any parameters, so it fails to compensate for the gap in limit's semantics.

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

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

The description states a specific verb (list) and resource (unanswered questions), and adds what is returned (frequency-ordered counts). It does not explicitly differentiate from siblings, but the purpose is unambiguous.

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

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

Usage is implied: an agent would use this to find knowledge gaps. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives (e.g., get_report or list_conversations).

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 message reaches the customer immediately on the original channel, and the agent pauses on that conversation — a state change the destructiveHint/openWorldHint flags do not spell out. It does not explicitly flag irreversibility or rate/error behavior, keeping it at 4 rather than 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, zero filler, with the primary action and its customer-visible effect front-loaded ahead of the secondary pause 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 3-param write tool with no output schema and strong annotations, the description covers the external side effect and the conversation-state consequence, which is what an agent most needs. Minor gaps remain around failure modes and what the call returns.

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

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

Schema coverage is 67%, with agent_id and conversation_id already carrying provenance notes ('from list_agents', 'from list_conversations'). The description only implies that 'message' is the free-text reply body and adds nothing about the 2000-character limit or content expectations, so it is baseline-level for the 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?

States a specific verb (send reply) and resource (conversation) with scope detail: 'on its original channel'. An agent can distinguish it from a knowledge/save tool, but the description never names the closest sibling (save_answer) or otherwise contrasts itself, so it misses the top band.

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

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

The sentence 'so you can continue by hand' plus the immediate-delivery and agent-pause clauses make the operating situation clear: a live human handoff to the customer. It offers no explicit when-not or alternative-tool guidance, so it stops short of 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?

Goes well past the annotations by disclosing the destructive effect in concrete terms (earlier saved answer is superseded), an outward-facing side effect (queues replies to waiting customers on connected channels), a cost (embedding credits per call), and the reason not to retry (new knowledge source each call, matching idempotentHint=false).

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

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

Four short sentences, front-loaded with the core action and its consequences, followed by the confirmation rule and the credit/retry caveat. No filler.

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

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

For a destructive, outward-facing, non-idempotent mutation with no output schema, the description covers the effects, the confirmation precondition, and the cost/retry pitfall. The remaining gap is return-value and partial-failure behavior, which is minor given the annotations already flag destructiveness.

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 agent_id is documented in the schema (33% coverage) and the description merely points back to list_agents implicitly via the schema. The description implies that question and answer are free text and that answer wording matters, but adds no format or length guidance beyond the structured constraints.

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 (save the correct answer to a customer question) plus the superseding semantics, which is more than a restatement of the name. It does not, however, draw the boundary against the sibling add_knowledge, leaving the agent to infer which one creates vs. replaces knowledge.

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 operating guidance: confirm wording and effects with the user before saving, and do not retry a successful save. Missing an explicit 'use add_knowledge instead when...' routing rule, so the alternative is implied 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 disclose that this is a non-read-only, idempotent, destructive, open-world operation. The description adds useful context by equating on:true with the dashboard's Enable embed and by stating that messaging channels are unaffected, though it does not explain the consequences of turning the widget off.

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 definition is two sentences, front-loaded with the core action and immediately followed by the important scope caveat. There is no filler or 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 simple two-parameter mutation with rich annotations and no output schema, the description gives enough context to call the tool correctly. A minor gap remains around the destructive implication of disabling the widget, but the destructiveHint annotation already signals that risk.

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

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

Schema coverage is only 50%, but the description compensates well for the boolean parameter by explaining exactly what on:true and on:false mean. The agent_id parameter is documented in the schema as coming from list_agents, so both parameters are sufficiently covered.

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

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

The description states a specific verb and resource: turning the agent's chat widget on the business website on or off. It also clarifies scope by saying messaging channels are not changed, which helps an agent distinguish this tool from broader channel-management work.

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 maps on:true to the dashboard's Enable embed action and on:false to disabling it, and explicitly excludes Telegram/WhatsApp management. It does not give a full decision rule for when to use this tool versus the dashboard for widget management, but the usage context is clear.

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

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

Annotations only declare it is a non-read-only, non-destructive, non-idempotent, closed-world call. The description adds genuinely non-obvious behavior: it consumes credits like a normal answer, and it does not create a customer conversation. It does not say whether tests are logged or retrievable afterward, 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?

Two tight sentences with zero filler: the first delivers purpose and the no-conversation constraint, the second delivers the cost implication. Front-loaded and appropriately sized.

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 states what comes back (answer and sources) and warns about credit consumption. Only the persistence/visibility of test results is left unstated, which is minor for a two-parameter 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 only 50% — agent_id is documented in the schema but question carries no description in either place. The description adds nothing about what the question should contain or any formatting constraints, so it fails to compensate for the coverage gap.

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

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

States a specific action (ask the agent a question), the result (answer plus sources), and the key scope distinction from siblings — no customer conversation is created, which separates it from reply_to_customer/get_conversation. An agent can identify it without opening the schema.

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

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

'Ask your own agent a question and see its answer and the sources it used' gives a clear context for use, and the no-conversation clause implicitly steers the agent away from reply_to_customer. No explicit exclusions or named alternatives are stated, so it stops short of a 5.

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

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

The annotations already flag the tool as destructive, open-world, and idempotent, and the description adds meaningful detail beyond them: qualifying a previously unqualified lead may create a sales opportunity and notify subscribed webhook endpoints. It also clarifies that repeating the same status does not repeat those transition effects, which is important operational context.

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 short sentences and front-loads the core action before explaining side effects. Every sentence contributes useful behavioral context without redundancy.

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

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

For a three-parameter mutation with no output schema, the description covers the most important behavioral concerns: overwrite semantics, qualification side effects, and idempotence. It does not explicitly state what happens when unqualifying a lead or whether any return value is produced, but the structured schema and annotations cover most remaining needs.

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

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

Schema coverage is 67%, with lead_id and agent_id documented in the schema. The description adds useful semantic meaning for the qualified boolean by explaining transition effects, but it does not document the ID parameters or provide parameter-level guidance beyond what the schema already contains.

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 precise verb and resource: 'Overwrite a lead's qualified status.' It clearly distinguishes this mutation from the sibling list/get tools and makes the scoped effect on the lead's qualification understandable.

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 implies the tool is used to change a lead's qualification status, but it does not explicitly state when to use this tool versus alternatives or when not to use it. It provides useful context about transition effects, but that is more behavioral detail than usage guidance.

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