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

With no annotations provided, the description carries the full disclosure burden. It adds useful behavioral context — the call returns the created agent's ID, and creation does not include the prompt, which is set in a separate follow-up call. It omits auth requirements, side effects, and reversibility, which are notable gaps for a creation 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 sentences, each earning its place: the action, the return value, and the follow-on step. The core purpose is front-loaded with 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 3-parameter create tool with no output schema, the description covers the action, the return ID, and the next step (update_agent_prompt), which is the key lifecycle context. Remaining gaps are minor — no guidance on what happens if all parameters are omitted (0 required) or how the returned ID is consumed by sibling tools.

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 documents name, language (with default and examples), and description. The tool description adds no parameter-level meaning 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 action and resource — 'Create a new AI agent in your organization' — with the verb 'create' cleanly distinguishing it from read siblings (get_agents), mutation siblings (update_agent_prompt, update_agent_config), and delete_agent. The return value (agent ID) is also disclosed, further clarifying the tool's contract.

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 explicitly routes prompt-setting to update_agent_prompt ('The agent prompt is set separately via update_agent_prompt after creation'), giving the agent a concrete when-not and sequencing cue. It does not, however, spell out when to prefer this over get_agents or update_agent_config, so the 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?

With no annotations provided, the description carries the burden. It usefully discloses the return contents and the 'at time of call' snapshot behavior, but does not explicitly state that it is read-only or has no side effects.

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 filler. The purpose is front-loaded, and the return-value list is dense but clear.

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 tool with no output schema, the description covers the return categories and provides an example ID. Minor omissions like explicit error behavior or guidance for obtaining a callId are acceptable given the tool's simplicity.

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 contains the same example CALL-1234567890-abc123. The description repeats that example without adding new parameter semantics 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 ('Deep-dive into a single call for debugging') and resource ('a single call'). Explicitly enumerates the returned data (transcript, errors, timing, cost, analytics, config), which distinguishes it from sibling tools like get_call_logs or get_usage_stats.

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 usage for in-depth investigation of a single call, but does not explicitly say when to use it over siblings or when not to use it. It does not mention that get_call_logs might be needed first to obtain a callId.

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

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

With no annotations provided, the description carries the full disclosure burden. It transparently states the soft-delete behavior, that the agent becomes inactive, and that it can be recovered. It could add more detail about side effects or return values, but the core behavioral traits are well covered.

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 two sentences with no unnecessary wording. It front-loads the core action ('Archive (soft-delete)') and immediately follows with the outcome and recoverability, making every word valuable.

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

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

For a simple one-parameter mutation tool with no output schema and no annotations, the description covers the essential operational context: what happens, why it is useful, and that it is reversible. It lacks explicit mention of response behavior, but that is a minor gap for this simple 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 'agent_id' adequately. The description adds 'by its ID' but does not provide further semantic detail beyond what the schema already states.

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 ('Archive (soft-delete)') and resource ('agent by its ID'), clearly stating the operation's nature. It also distinguishes itself from create/update siblings by emphasizing the deletion/deactivation aspect and the recoverable soft-delete behavior.

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

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

The description clearly implies when to use the tool: when an agent should no longer be active but may need recovery later. It does not explicitly name alternatives, but no sibling offers a delete/archive operation, so the usage context is reasonably 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists agents and returns configuration fields, which implies a read-only operation. It does not disclose pagination behavior, rate limits, or whether the result includes non-archived agents by default, though the schema covers defaults.

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

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

The description is a single sentence that front-loads the primary action and resource, then lists the useful return fields. Every word contributes meaning, and there is no redundant or filler content.

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 list tool with fully documented optional parameters, the description covers the core purpose and return content. It does not fully replace the lack of an output schema, but it names the key return fields and is sufficient for an agent to decide when to call it.

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

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

The input schema already provides 100% description coverage for all three parameters (limit, agent_name, include_archived). The tool description adds no parameter-specific meaning beyond saying the result includes configuration and call statistics, so the baseline of 3 applies.

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

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

The description clearly states the tool lists AI agents in the organization and specifies the resource type, distinguishing it from sibling tools dealing with campaigns, call logs, or phone numbers. It does not explicitly name any sibling alternative, but the resource 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?

The intended use case is implied: use this when you need to list agents and view their configuration. However, there is no explicit guidance about when not to use it or how it compares with related tools like get_campaigns or get_call_logs.

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?

No annotations are provided, so the description carries the full burden. It discloses return contents (metadata, duration, cost, errors, transcript summary), which is useful, and the 'get' verb makes the read-only nature apparent. However, it does not mention pagination behavior tied to the limit parameter, result ordering, date-range inclusivity semantics, or any rate-limit or auth considerations.

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

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

Three short sentences with no filler: purpose is front-loaded, followed by the filter capabilities and the return-value summary. Every sentence earns its place, and the description is appropriately sized for an 8-parameter read 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?

Since there is no output schema, the description correctly explains return values, which helps. However, with 8 parameters and zero annotations, an agent is left guessing about pagination, result ordering, and how the omitted has_errors filter works. It also leaves no guidance for distinguishing this from debug_call. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including details the description lacks (partial match for agent_name, fromNumber/toNumber/userNumber matching for phone_number, enum values). The description's filter list is largely redundant with the schema and even omits the has_errors filter, so it adds no real parameter meaning beyond baseline.

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

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

The description states a specific verb and resource ('Get call logs for your organization') with clear scope, and names several filter dimensions and return fields. It is unambiguous about what the tool does, but it does not explicitly distinguish itself from siblings like debug_call or get_usage_stats, which both concern call-related data.

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 context is implied by the filter list ('Filter by status, type, date range, agent name, or phone number'), which signals this is the bulk call-log retrieval tool. However, there is no explicit guidance on when to choose this over debug_call (individual call troubleshooting) or get_usage_stats (aggregate statistics), and no exclusions 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It does convey that this is a read-only listing operation scoped to the organization, which is non-trivial. However, it discloses nothing about pagination, ordering, how 'progress' is defined, or result boundaries beyond what the schema's limit parameter already implies.

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

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

Two sentences with zero filler. The core purpose is front-loaded in sentence one, and the output-field detail in sentence two earns its place by telling the agent what to expect in the results. Nothing extraneous.

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 list tool with fully documented optional parameters, the description is mostly sufficient. Gaps remain: no output schema exists so the field list is the only return-shape signal and it is partial, no pagination behavior is described, and there is no guidance distinguishing this from get_call_logs — a genuine ambiguity risk among the siblings.

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% — limit, status, and agent_name each have descriptive text in the schema, so the baseline of 3 applies. The description adds no parameter-specific meaning; 'agent used' refers to an output field, not the agent_name filter 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?

States a specific verb and resource: 'List outbound calling campaigns for your organization.' The second sentence clarifies what fields are returned (status, progress, agent used, audience size), which is useful. It doesn't explicitly name or differentiate against siblings like get_call_logs, but the resource entity (campaigns vs. calls) is inherently distinct.

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 context is implied rather than stated: an agent can infer this tool is for listing campaigns, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives like get_call_logs for call-level detail. Given several listing tools among siblings, explicit routing would help.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It clearly signals a read-only listing action and describes the output's content, which is useful. It does not mention pagination, authorization requirements, or edge cases, but the simplicity of the operation makes this a moderate gap rather than a severe 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?

The description is a single, efficient sentence that front-loads the verb and resource, then lists the key output fields. Every word earns its place, and there is no redundant or vague 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 zero-parameter, low-complexity listing tool, the description is nearly complete: it states scope, action, and return fields. It could add a note about auth requirements, pagination, or empty-result behavior, but those are minor omissions given the tool's simplicity.

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, so parameter semantics are essentially moot; the baseline for this case is 4. The description still adds value by explaining what each returned phone number record contains, compensating for the absence of an output schema.

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

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

The description uses a specific verb ('List') with a clear resource ('phone numbers acquired by your organization') and enumerates the returned fields (number, country, capabilities, assigned agent). This clearly differentiates it from sibling tools like get_agents or get_call_logs.

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 its usage context: browsing the organization's phone numbers and their assignments. However, it does not explicitly state when to prefer this tool over alternatives or provide any exclusion criteria. Still, for a zero-parameter list operation, the intended use is reasonably evident.

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?

No annotations are present, so the description carries the burden. It discloses that this returns organization-level aggregate statistics, which implies read-only behavior, but it does not explicitly state that no data is modified, who can access it, or any limitations on the aggregation. This is acceptable but not thorough.

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?

First sentence is front-loaded with the core function and key output metrics. The second sentence is somewhat generic but reinforces the use case; overall there is little 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?

With no output schema and no annotations, the description must cover return semantics. It lists the main metric categories but does not mention output format, grouping, or how filters interact with the aggregate result. Sufficient for basic invocation but leaves some ambiguity.

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 start_date, end_date, and agent_name. The description adds no parameter-level detail, but it also does not need to; baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Get call usage statistics for your organization') and enumerates the output categories (total calls, duration, costs, status breakdown). It is clear, though it does not explicitly contrast itself with sibling tools like get_call_logs beyond the implicit aggregate-vs-logs distinction.

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?

'Useful for understanding usage patterns and costs' gives a soft use case, but there is no explicit guidance on when to choose this over get_call_logs or other siblings, nor any exclusions. The usage context 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?

No annotations are provided, so the description carries the burden of disclosing behavior. It explicitly states that the agent will call the number and follow its configured prompt, which reveals the side-effecting nature of the tool. However, it omits potential consequences such as call charges, asynchronous behavior, failure modes, or whether the call actually connects.

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 two short sentences with no filler. The primary action is front-loaded, and the second sentence adds useful behavioral context about the agent following its configured prompt.

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 parameters are fully documented in the schema and the purpose is clear, but the description lacks usage exclusions, side-effect caveats, and any indication of what happens after the call is initiated. With no output schema and no annotations, slightly more context would make the tool fully self-sufficient.

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 each parameter already has a meaningful description, including E.164 format for phone_number and the ownership constraint for from_number. The tool description adds little parameter-specific meaning beyond referring to the provided phone number and the configured agent prompt, so the baseline of 3 is appropriate.

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

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

The description starts with a specific verb ('Initiate') and a clear resource ('outbound phone call'), and it clarifies that the call is made by a specific agent. It is unambiguous about the core function, though it does not explicitly distinguish this tool from siblings like debug_call.

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

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

The description gives no when-to-use or when-not-to-use guidance and names no alternative tools. The intended usage is only implied by 'Initiate an outbound phone call,' which is insufficient given the presence of debug_call and other related tools in the sibling list.

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

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

With no annotations, the description carries the full burden. It adds the key behavioral detail that only provided fields are updated, but it omits other behavioral aspects such as side effects, required permissions, validation failures, or whether the update is synchronous. Some transparency is present, but not comprehensive.

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 two concise sentences with no wasted words. The core action and the critical partial-update behavior are front-loaded, and the alternative tool is mentioned immediately after.

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 is complex with 9 parameters and nested objects, but the schema is rich and covers all parameters. The description adds the essential context of partial updates and correctly routes prompt-specific changes. Without annotations or an output schema, a brief note on return value could help, but it is not necessary 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 description coverage is 100%, so the input schema already documents all parameters in detail. The description mentions general categories (name, language, first message, voice settings) but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool updates an agent's configuration (name, language, first message, voice settings) and distinguishes it from update_agent_prompt. It uses a specific verb and resource, making the tool's function 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 description explicitly notes that only provided fields are updated, which clarifies partial-update behavior. It also names update_agent_prompt as the alternative for prompt/instruction updates, giving the agent a clear routing decision.

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

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

With no annotations, the description carries the burden of disclosing behavior. It states that the operation updates the agent's prompt and workflow, and the 'full new prompt text' wording indicates wholesale replacement. It does not mention permissions, side effects, reversibility, or return behavior, but for a simple setter the replacement semantics are the most important trait.

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

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

The description is compact and front-loads the action and target. The final sentence is slightly redundant with the first, but the overall length is appropriate and there is little 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 simple two-parameter mutation tool, the description is mostly adequate: it names the target, the value to pass, and the effect. However, it lacks any mention of alternatives, return values, or edge cases, and with no annotations there is no safety or side-effect context beyond the basic replacement behavior.

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. The description adds a small nuance by stressing 'full new prompt text,' which clarifies that the prompt parameter is a complete replacement, but it does not add substantial meaning 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 clearly states a specific verb and resource: 'Update an agent's system prompt / instructions.' This distinguishes the tool from general agent config tools, though it does not explicitly call out sibling tools such as update_agent_config. The phrase 'Pass the full new prompt text' also signals replace semantics.

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

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

The description gives a practical usage hint: 'Pass the full new prompt text,' implying the caller must provide the complete replacement rather than a partial update. However, it provides no explicit guidance on when to use this tool versus alternatives like update_agent_config or when not to use it.

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