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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior that annotations cannot express: it is a paid call ($0.75), payment runs through MPP/Stripe, and a failed call surfaces as JSON-RPC error -32042 that must be retried with a credential in params._meta. That is exactly the kind of operational context the annotations lack.

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 fragments, front-loaded with cost, then capability, then payment mechanics. Nothing is padded, though the payment instruction is dense in quoted identifiers and slightly interrupts the flow of the purpose statement.

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 tool with an output schema and solid annotation coverage, the description covers cost and payment adequately. What it omits is the differentiator against the many similar 'global' siblings and any sense of what the signal actually returns, which matters for a tool an agent must choose among ten options.

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 declared parameters, so the baseline is 4. The description goes slightly beyond by documenting an out-of-schema runtime field, params._meta["org.paymentauth/credential"], which an agent would otherwise have no way to discover from 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?

The description identifies the resource as 'global directional market intelligence' and hints at method ('measured lead/lag evidence', 'invalidation logic'), but it is an abstract noun phrase rather than a concrete verb+output. With siblings like shadowgraph_global_brief, shadowgraph_global_snapshot, and shadowgraph_market_recap, an agent gets no basis for telling this tool apart from them.

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?

There is no guidance on when to call this tool versus its nine siblings, nor any stated prerequisites or exclusions. The only procedural advice concerns payment retry mechanics, which is invocation logistics rather than usage selection.

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