Ninar AI

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

The description adds significant behavioral context beyond annotations: it specifies the exact model consensus flow (Haiku 4.5 + Gemini Flash, escalating to Sonnet 4.6 + Gemini Pro), use of a versioned taxonomy, required plan (Pro or higher), and the return format (Why Drawer headline, audit trail, per-model judgments). This fully discloses the tool's internal behavior and constraints, complementing the readOnlyHint and idempotentHint annotations.

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: the first states the purpose with a concrete example, the second explains the methodology, outputs, and requirements. Every sentence is earned, no filler, and the most critical information is front-loaded.

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 lacking an output schema, the description explicitly lists return components (headline, audit trail, per-model judgments). It also covers the plan requirement. The nested object in input schema is adequately described in the schema itself. Given the tool's complexity and the coverage of annotations, this description completes the picture well.

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?

With 100% schema description coverage, the baseline is 3. The description adds value by providing an example for entity ('Banner Life') and implying that raw_evidence should contain source text. It also clarifies the default taxonomy_id. This enriches understanding beyond the schema alone.

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 runs a System of Record adjudication on an entity surfaced by an AI engine, with an example (e.g., 'Banner Life'). This specific verb+resource combination distinguishes it from sibling tools like generate_content or scan_visibility.

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 validating brand entities against a versioned taxonomy using dual-model consensus, but does not explicitly state when to use this tool versus alternatives or when not to use it. The context from sibling names helps, but the description could be more directive.

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 value beyond annotations by noting 'Returns full content text inline — no need to visit the dashboard' and the plan requirement. However, annotations already indicate non-destructive nature, and no further behavioural details (e.g., rate limits, state changes) are provided.

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 concise sentences. The first clearly states the purpose; the second adds benefits and constraints. 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?

Given one parameter with 100% schema coverage and no output schema, the description adequately explains the return format ('full content text inline') and the access requirement. Sufficient for selection and 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 coverage is 100% with a well-described enum. The description adds minimal extra value by clarifying the 'all' option usage; the schema already explains the parameter sufficiently.

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 specifies the verb 'generate' and the resource 'AI-optimized content for gaps', listing specific content types (FAQ, about copy, etc.). It clearly distinguishes from sibling tools like list_content_gaps and scan_visibility.

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?

States the requirement 'Pro plan or higher required' explicitly. It implies usage when content is needed for gaps, but does not explicitly mention when not to use or provide alternatives like visiting the dashboard.

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, and destructiveHint, so the description does not need to repeat those. It adds behavioral details like 'most recently scanned brand' and 'broken down by engine', plus the account requirement. No contradictions.

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 consists of two concise sentences with no fluff. The first sentence front-loads the purpose, and the second adds a necessary prerequisite. Every word earns its place.

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 tool with no parameters and no output schema, the description explains the return value (score range, breakdown) and required account. It lacks details on error cases (e.g., no scanned brand) or format of breakdown, but is largely 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?

The tool has no parameters, so the baseline is 4. The description adds meaning beyond the empty schema by explaining the output range and breakdown, which is valuable for an agent selecting the tool.

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 retrieves the AI Visibility Index (0-100) for the signed-in user's most recently scanned brand, broken down by engine. It uses a specific verb and resource, and the purpose is distinct from sibling tools like audit_brand_visibility or scan_visibility.

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 provides a clear prerequisite: requires a free Ninar account. It implies usage for checking the latest score, but does not explicitly state when not to use it or suggest alternatives. Sibling tool names give context, but explicit guidance would improve this dimension.

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=true, idempotentHint=true, destructiveHint=false. Description adds value by specifying that results are scoped to the signed-in user and come from the latest scan, which goes beyond annotation information. No contradictions.

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?

Single sentence with clear structure, front-loaded with action and resource. No unnecessary words.

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 no output schema, the description gives a good sense of return value (FAQs, differentiators, use cases, about copy). For a simple list tool with no parameters, this is 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?

No parameters exist (0 params), and schema coverage is 100%. Baseline is 4 per the rule. Description does not need to add parameter information.

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?

Description clearly states the tool lists AI-generated content suggestions (FAQs, differentiators, use cases, about copy) for the signed-in user, tied to their latest scan. This is specific and differentiates from siblings like audit_brand_visibility, generate_content, get_latest_score, and scan_visibility.

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 after a scan by mentioning 'latest scan', but does not explicitly state when to use this tool vs alternatives like audit_brand_visibility or generate_content. No when-not guidance is provided.

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 set openWorldHint=true and readOnlyHint=false; the description adds behavioral context: the tool queries multiple engines (open-world), engine count scales with plan, and the scan is not idempotent (implied by 'run a scan'). It does not contradict annotations and provides meaningful behavioral details beyond them, though it omits information on rate limits or result format.

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. The first clearly states the tool's purpose, and the second efficiently explains the two modes and plan-dependent behavior. No extraneous information, perfectly front-loaded.

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 the missing output schema, the description could briefly mention what the scan returns (e.g., scores, mentions). However, it covers the core purpose, modes, and plan scaling adequately for agent selection. It is mostly complete but leaves the output format unspecified.

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?

Input schema covers 100% of parameters with descriptions. The description adds extra meaning by explaining the dual role of `city` (local vs. GEO scan) and gives examples for `category`, but does not significantly elaborate on other parameters beyond what the schema provides. With high schema coverage, baseline is 3.

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 explicitly states the tool runs an AI visibility scan for a brand. It distinguishes two modes (local-business check with city, multi-engine GEO scan without city) and names specific engines (ChatGPT, Gemini, Perplexity, Claude, AI Overviews), making it distinct from siblings like audit_brand_visibility.

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 provides clear guidance on when to include or omit the `city` parameter to switch between scan types, and mentions plan-dependent engine scaling. It lacks explicit 'when not to use' or alternative tool references, but the context is sufficiently clear given sibling differentiation.

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