Dante IX — Brand & GEO Intelligence

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds material context beyond them: deterministic synthesis under 300ms, zero LLM calls, never touches external sites, consumes no live audit credits, and degrades to a 30% preview without an API key versus full sealed output with a paid key. Tier/domain-slot limits are also disclosed, which 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-loaded with the artifact list, then organized into labeled sections (Side effects & latency, Constraints, Auth & quota, When to use) that scan well. It is long and restates return keys that the existing output schema already documents, which is the only waste.

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 multi-input synthesis tool with auth tiers and cross-field constraints, everything an agent needs to call it correctly is present: required inputs, constraint invariants, cost/credit behavior, latency, and the preview-vs-full-key distinction. Return values are covered by the output schema, so the description needn't go further.

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 earns above that by documenting cross-field constraints not in the schema — `brand_name` must match the stem of `domain_url`, and URLs inside `official_facts` must belong to `domain_url`. It doesn't add per-parameter guidance beyond those invariants, so not a 5.

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 (Generate) and a concrete set of resources (`/llms.txt`, `/.well-known/ai-catalog.json`, Schema.org JSON-LD types, robots.txt AI-crawler rules), so an agent knows exactly what artifact comes back. It is clearly separable from siblings like `dante.run_audit` or `dante.remediate_hallucination`, which are named.

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 'When to use' clause plus an explicit alternative with its triggering condition ('use `dante.remediate_hallucination` instead when countering a specific false AI claim'). This is routing guidance an agent can act on without opening either schema.

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 read-only, idempotent, open-world and non-destructive traits, but the description goes well beyond them: sub-1s vs 4-12s latency, $0 preview mode when DANTE_API_KEY is omitted, and the 1-credit monthly quota for live probes. These are the operational details an agent needs before spending a paid credit.

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 purpose, then segmented into 'Side effects & latency', 'Auth & quota', and 'When to use' labels, which scan well. It is on the long side and briefly restates the readOnlyHint annotation, 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?

A live, quota-consuming probe with an output schema and 5 parameters is well served here: latency, cost, auth requirements, output fields, and sibling routing are all covered. An agent can call it correctly without checking anything else.

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% with enum descriptions for lang and vertical_mode, so the baseline is 3. The description adds real value by explaining the cost/latency consequence of live=true and the preview-mode fallback, though it does not touch on vertical_mode selection beyond what the enum labels already say.

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 pair ('Measure GEO Share of Model and First-Choice Win Rate') with named engines (OpenAI, Gemini, Perplexity), so the agent knows exactly what is produced. It also explicitly tells the agent how this differs from dante.run_audit and dante.remediate_hallucination.

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 'When to use' paragraph names two alternatives with the exact conditions that select them: run_audit when social sentiment/sarcasm/bot detection is needed, and remediate_hallucination when a specific false claim must be fixed. No inference is left to the 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?

Annotations already cover the safety profile, but the description goes well beyond them: sub-200ms latency, determinism, zero external LLM cost, zero audit-credit consumption, and explicit tenant isolation ('never accesses or leaks signals belonging to other tenants'). Critically, it discloses the credential-dependent behavior — without DANTE_API_KEY a free-trial sandbox returns a 30% preview, while a dnt_live_ key returns full records — which materially changes how an agent should interpret matched_count and result completeness.

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?

Long but deliberately segmented into labelled blocks (Returns, Side effects & latency, Auth & quota, When to use) that let an agent jump to the relevant clause. Every sentence carries routing, safety, or quota information 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 a 3-parameter read tool this covers the decision-relevant surface: scope, cost, latency, tenant isolation, and the credential tier that determines result completeness. The only slack is that it enumerates return fields (`query`, `voice_filter`, `matched_count`, `records`, `tier_mode`) that an output schema already declares, which is mild duplication rather than an information 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 coverage is 100% and the schema already documents all three parameters including the voice_filter enum values and limit bounds, so the description need not compensate. The description adds only a runnable boolean query example ('pricing OR billing OR delay'); it says nothing about how voice_filter or limit affect results, so it earns baseline rather than above 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?

The first sentence names a specific verb (search) and a precisely scoped resource (the caller's isolated tenant signal vault) and enumerates the record types returned (complaints, calibrated sentiment, bot alerts, competitor gaps). It also explicitly excludes sibling responsibilities, so an agent can distinguish it from dante.probe_geo_share and dante.forge_geo_shield 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?

Provides an explicit 'When to use' trigger (inspecting recurring pain points after running dante.run_audit) and a 'Do not use' clause that names the two alternative tools for the excluded cases. Both the positive and negative routing conditions are stated, leaving nothing 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?

Beyond the annotations, the description discloses latency (<300ms), determinism, no external LLM calls, zero destructive behavior, credit consumption, and preview-mode behavior depending on API key. These are meaningful operational behaviors not captured by 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 description is dense but well structured, using inline labels for side effects, security constraints, auth, and when-to-use. It is front-loaded with the purpose and return package, and every sentence contributes actionable context.

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?

Despite having an output schema, the description still clarifies return artifacts and modes of operation. Combined with auth, quota, security constraints, and sibling-tool routing, it gives an agent everything needed to invoke the tool correctly.

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 schema already documents individual parameters. The description adds cross-parameter constraints the schema does not convey: brand_name must match the stem of domain_url, and verified_fact must not contain third-party foreign URLs.

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 precise verb and resource: 'Synthesize structured semantic counterweight artifacts to correct an inaccurate or outdated claim' about a brand. It explicitly names the output artifacts and distinguishes itself from sibling tools like dante.forge_geo_shield and dante.probe_geo_share.

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 exactly when to use this tool: when an AI assistant actively states false pricing, wrong features, or outdated ownership about a brand. It also names alternative tools for different scenarios, such as forge_geo_shield for site-wide generation and probe_geo_share for citation checking.

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 (which only say openWorld=true, destructive=false, idempotent=true) by disclosing the persistence side effect — an isolated snapshot written to the caller's tenant vault that later feeds dante.query_street_friction. It also quantifies latency under both live_geo modes and explains auth/quota: unauthenticated runs force live_geo=false with 30% redacted preview at $0, while paid keys consume one monthly quota unit per live call.

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 side effects and latency, then auth, then tool routing — a sensible reading order that lets an agent stop early. Docked one point because the parenthetical enumeration of return fields (audit_id, fsm_state, som_score, ...) duplicates the output schema it already has.

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 costly, network-touching, tenant-persisting operation this covers everything an agent must know before calling: cost model, latency, side effects, redaction, and sibling routing. Return values are covered by the output schema and the description need not restate them.

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 earns an extra point by adding cross-parameter behavior the schema cannot express — notably that omitting DANTE_API_KEY overrides live_geo to false regardless of the caller's value, and that live_geo drives the <1s vs 5-15s cost. It does not elaborate on csv_path or vertical_mode beyond what the enum descriptions already give.

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 (Execute) and a precisely scoped resource: a 9-dimension brand reputation, social sentiment, and GEO audit across ChatGPT, Gemini, and Perplexity. An agent can distinguish this full diagnostic from the narrower siblings (a citation-only probe, an asset generator) 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?

Includes an explicit 'When to use' clause plus two named alternatives with the exact conditions that select them: dante.probe_geo_share for a fast Share-of-Model check without social listening, dante.forge_geo_shield when brand facts are already known. Exclusion criteria and alternatives are both spelled out.

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