territory_trigger_scan

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It discloses 'triggers a live re-scan' but gives no details about whether the call blocks, what it returns, whether re-scan is asynchronous, or whether repeated triggers have side effects. This is a notable gap for an action that starts background work.

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 core action of 'Triggers a live re-scan' and includes the full scope without wasted words. It is appropriately concise, even it does not fully explore edge cases or 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?

Given that there is no output schema and no annotations, the description needed to explain return behavior and side effects, and it doesn't. An agent knows what the tool does, but cannot predict what a successful call returns or whether the operation is asynchronous or potentially destructive, leaving the description incomplete for this context.

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 is an empty object with zero parameters, so the schema already fully documents the parameter space. The description adds no parameter details because none are needed, matching the 0-parameter 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 uses a specific verb–resource pairing: it 'triggers a live re-scan' of news and signal triggers across monitored accounts. This conveys a distinct, non-read-only purpose that differentiates it from related tools like territory_get_signals, though it does not explicitly name alternatives.

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 'across all monitored accounts in your territory' tells the agent the operational scope, but nothing explicitly states when this tool should be preferred over related alternatives such as territory_get_signals or territory_preview_signals. The intended usage is implied rather than clearly prescribed.

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