B4 Index

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

The description goes far beyond the readOnlyHint annotation by disclosing the B4 methodology v4.0 banding behavior, the ±1 uncertainty band on three quadrant dimensions, the exact confidence word thresholds (clear ≥70%, lean ≥50%, split <50%), the near-call flag at 15 points, the strict 3.5 line for 'high' axes, tie-breaking order (BUY → BRIDGE → BEWARE → BUILD), and the org lens semantics (shifts AI-feasibility band center by −1/0/+1, never stored, never changes raw scores). It also warns that confidence is sensitivity under a fixed band, not project-success probability, and instructs agents to follow the guidance block rather than substituting their own build-vs-buy prior. This is exceptionally transparent.

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 long but every section earns its place: input format, resolution behavior, output structure, methodology, confidence semantics, org lens, routing, and clarification handling. It is front-loaded with the core purpose and example, then progressively details methodology and routing. The only minor deduction is that the methodology section is dense and could arguably be trimmed, but for a tool with this complexity, the length is justified.

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 tool's complexity (banded verdicts, five dimension scores, two axes, urgency, vendors at access depth, guidance blocks, clarification handling, org lens), the description covers all operational aspects an agent needs: input format, resolution fallback, clarification protocol, output contents, confidence interpretation, tie-breaking, and routing to siblings. The output schema exists and the description references its key fields without needing to enumerate them. Nothing critical is missing 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 coverage is 100%, so the schema already documents both parameters thoroughly. The description adds value by explaining the org lens semantics ('shifts the center of the AI-feasibility band by −1 / 0 / +1 and nothing else', 'a filter the caller looks through, never a stored profile', 'choose it from delivery capability, not headcount') and by clarifying the tools array's resolution behavior (resolves by name when indexed, otherwise by description, otherwise clarification.needed). The description also adds the max-100-per-call constraint context and the example format. It doesn't add much beyond the schema for the org parameter since the schema already covers it, but the tools array resolution semantics are genuinely additive.

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 opens with a specific verb ('Audit a stack') and immediately defines the input shape with a concrete example. It clearly distinguishes this tool from siblings by stating it handles vendor/product names, while b4_recommend handles needs, b4_score handles exact categories, and b4_compare handles build-vs-buy paths. The routing section explicitly names each sibling and its trigger condition, making the purpose unmistakable.

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 an explicit routing section: 'a vendor or product name → b4_audit; a need or problem in words → b4_recommend; an exact category name or id → b4_score or b4_compare; browsing/filtering/unknown vocabulary → b4_browse.' It also gives a concrete example of when to add a description ('for anything the index may not know') and instructs how to handle clarification.needed results by relaying askTheUser and re-running with the answer. This is exemplary usage guidance.

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?

Even though annotations already mark this as read-only, the description adds substantial behavioral context: industry filters return vertical plus horizontal categories, verdicts are banded rather than point calls, ties break in a defined order, the org lens shifts reading but never changes raw scores, and the lens is never stored. This goes well beyond the annotation signals.

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 long, but it is front-loaded with the core purpose and an example, then organized into capability, methodology, lens, routing, and plan sections. The dense verdict-methodology paragraph is relevant for correct interpretation, though it could be tightened without losing essential meaning.

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 tool with 8 parameters, an output schema, and complex verdict semantics, the description is remarkably complete. It covers the filtering behavior, the banding methodology, the org-lens effect, sibling routing, contingency handling (clarification.needed), and licensing context. Nothing an agent needs to invoke it correctly is missing.

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 handles most parameter documentation. The description nonetheless adds real meaning beyond the schema for industry (returns vertical + horizontal categories) and quadrant (matches the verdict at whichever lens is active), while clarifying the org lens semantics and default behavior. Not every parameter receives extra treatment, but the ones that need nuance are covered.

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 opens with a specific purpose — 'browsing, filtering, or finding the index's name for something' — and supports it with a concrete example. It also differentiates b4_browse from its siblings by explicitly naming when not to use it, so an agent can disambiguate before opening any schemas.

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 Routing paragraph is explicit and actionable: vendor/product names go to b4_audit, worded needs go to b4_recommend, exact category names go to b4_score/b4_compare, and browsing/filtering/unknown vocabulary goes to b4_browse. It also gives guidance on choosing the org lens and notes the B4 plan requirement.

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?

Although the annotations provide readOnlyHint=true, the description adds substantial non-obvious behavior: verdicts are banded rather than point calls, uncertainty bands shift verdicts, ties break in a specific order, axes count as high only at 4+, confidence is sensitivity under a fixed band rather than success probability, and the org lens is a read-time filter that never alters stored scores. This goes well beyond what annotations alone convey.

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 long but densely packed with information that an agent needs to invoke the tool correctly and interpret its output safely. It is front-loaded with the core purpose and example, then flows logically through output contents, methodology, confidence semantics, org lens, and routing. Few sentences are redundant; the length is justified by the tool's complexity.

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 tool with an output schema, the description covers everything an agent needs: what triggers this tool versus its siblings, the full contents of the structured output, the meaning and caveats of the verdict, how to handle the org lens, how to relay askTheUser for audit clarification, and the access requirement distinction. No material gap remains.

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 schema already documents both parameters at 100% coverage, and the description still adds value: it gives a concrete example for category, explains the org lens as a maturity-based filter chosen by delivery capability rather than headcount, describes the band shift (−1/0/+1), and notes that omitting org returns the published default-lens numbers. This is meaningful semantic enrichment 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 names a specific verb and resource: compare a category's build path versus buy path for one exact category name or id, with an example payload. It clearly distinguishes itself from b4_score, which is specifically called out as 'for the scores alone,' and from the browsing and recommendation siblings via the routing block.

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 routing section is explicit and actionable: it tells the agent to use b4_audit for vendors/products, b4_recommend for needs/problems, b4_browse for browsing or unknown vocabulary, and b4_compare only for exact categories when the question is build vs buy. It also states when to use b4_score instead and how to handle audit clarification responses. No inference is required.

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 only declare readOnlyHint=true and openWorldHint=false, so the description carries the behavioral burden. It explains that verdicts are banded with ±1 uncertainty, defines confidence words and near-call flags, states the tie-break order (BUY → BRIDGE → BEWARE → BUILD), and clarifies confidence is 'sensitivity under a fixed band, not project-success probability.' No contradiction with 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 long, but it is organized into functional blocks (purpose, verdict mechanics, org lens, routing) with no filler. The core purpose and example appear first, while detailed methodology is placed after. The length is justified by the tool's complexity, though it is denser than strictly necessary.

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 description covers the input contract (need/problem in words, not vendor name), the output philosophy (banded verdict with distribution, confidence word, guidance), the org lens semantics, and routing to sibling tools. With an output schema present, the description does not need to detail return fields, yet it still summarizes what the structured output contains. Nothing an agent needs to invoke this tool correctly is missing.

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 schema covers all four parameters with descriptions, so the baseline is 3. The description adds extra value: it gives a concrete example for `description`, clarifies that `org` is a read-time lens that shifts the AI-feasibility band by −1/0/+1 and is never stored, and notes that omitting it yields default-lens numbers. This elevates it above the schema 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 opens with a concrete example and explicitly states it 'Get[s] B4 Index recommendations from a natural language description of a software need or business context,' naming a specific verb and resource. It also distinguishes itself from siblings via the routing table ('a need or problem in words → b4_recommend'). This is specific and differentiating.

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 an explicit routing table mapping input types to tools: vendor/product names to b4_audit, exact category names/ids to b4_score or b4_compare, browsing to b4_browse, and needs/problems to b4_recommend. It also tells the caller to ask when org capability is unclear and how to handle clarification.needed downstream. Clear when-to-use and exclusion guidance.

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?

Even though readOnlyHint=true already indicates a safe read operation, the description adds substantial behavioral detail: banded verdicts, ±1 uncertainty bands, confidence word thresholds, tie-breaking order, the strict 3.5 cutoff for high axes, and the org lens being a transient filter rather than a stored profile. It also explicitly disclaims that confidence is sensitivity under a fixed band, not project-success probability. No contradiction with 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 long but every section earns its place: example, modes, output contents, methodology constraints, org lens semantics, and routing. It is front-loaded with the core invocation pattern. The density is justified by the tool's complexity, though it is not concise in an absolute sense.

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 complex tool with four parameters and a rich output schema, the description is complete: it covers input modes, output structure, verdict semantics, confidence interpretation, organiational lens behavior, evidence inclusion, and cross-tool routing. The structured output schema already carries return details, so the description does not need to 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, but the description meaningfully enriches the parameters with a concrete example, clarifies that scores is for custom evaluations, explains what includeEvidence adds to the payload, and stresses that the org lens only shifts the AI-feasibility band center and never changes raw scores. This exceeds the schema's own descriptions.

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 opens with a specific verb and resource: score one exact category name or id using the B4 Index. It clearly delineates two modes (pre-computed scores for known categories, custom evaluation via raw dimension scores), and the routing paragraph explicitly distinguishes this tool from b4_audit, b4_recommend, b4_compare, and b4_browse.

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?

Routing guidance is explicit: vendor/product names go to b4_audit, needs/problems to b4_recommend, exact category names/ids to b4_score or b4_compare, and browsing/unknown vocabulary to b4_browse. It also clarifies when to use b4_score vs b4_compare and when to include evidence or set the org lens, leaving no ambiguity about tool selection.

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