B4 Index

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

The description goes far beyond the readOnlyHint annotation, explicitly stating that the org lens is never stored, no user attribute is saved/inferred, and the scores never change. It also transparently details the banding methodology, confidence thresholds, near-call flag, and tie-breaking rules. This is exemplary behavioral disclosure beyond 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 sentence carries essential methodology or usage detail. It is front-loaded with the core function, then progressively explains uncertainty, parameter effects, and sibling tools. No redundancy or filler phrases are present.

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 there is no output schema, the description thoroughly describes the return value: per-tool banded verdicts, portfolio summary, verdict distribution, BEWARE spend, near calls, priority actions, confidence words, and tie-breaking. It also covers edge cases like the 3.5 threshold and tie-breaking order, making the description effectively complete for an agent to invoke and interpret results.

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 already has descriptions for both parameters (100% coverage). The description adds valuable semantics for the 'org' parameter, explaining it shifts the AI-feasibility band center by −1/0/+1 and is a read-time filter, and it gives an example of the 'tools' parameter. This exceeds the baseline of 3 but is not a full 5 because the schema already handles the basic meaning.

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's function: analyzing a software stack against the B4 Index and producing per-tool verdicts plus a portfolio summary. It distinguishes from siblings by noting the free tools (b4_browse and b4_score) and implies this is the stack-audit tool compared to single-score or browsing tools.

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 context: use when you have a list of tools/categories to audit as a portfolio. It mentions that b4_browse and b4_score are free, implying these are alternatives for individual operations, but it does not explicitly state when to use b4_compare or b4_recommend over this tool, so it falls short of explicit when-not-to-use 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?

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral detail: the banded verdict methodology, confidence words (clear/lean/split), near-call flags, tie-breaking order, and the org lens semantics (shifts band center, stored nowhere, does not change scores). This goes well beyond the annotation and fully informs the agent of edge behaviors and privacy-safe operations.

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 front-loaded with the primary purpose, then systematically explains the verdict system and edge cases. Every sentence earns its place given the methodological complexity, but the length is borderline for a simple browse tool and could be tightened without losing essential information.

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 tool's behavior thoroughly, including output semantics (verdict, distribution, confidence, near-call) and the org lens, which compensates for the absence of an output schema. Minor gaps remain, such as an explicit statement of pagination or exact response format, but the essentials are present.

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 descriptive parameter entries, setting a baseline of 3. The description adds important context beyond the schema by explaining the org lens effect (−1/0/+1 shift, no persistence) and the quadrant tie-breaking rule (BUY→BRIDGE→BEWARE→BUILD), which are not in the schema. This added value justifies a 4.

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 leads with a specific verb+resource: 'Search and filter the B4 Index's 1,600+ independently scored software categories.' This clearly distinguishes browse from sibling tools like b4_audit, b4_compare, b4_recommend, and b4_score, which have different intents.

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 usage context by listing the axes to browse (keyword, domain, quadrant, industry) and the optional org lens. It does not explicitly contrast with alternatives, but the sibling names make differentiation obvious, and the behavior is well-scoped for browsing rather than auditing or scoring.

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?

The description goes far beyond the readOnlyHint annotation. It explains the banding methodology (±1 uncertainty bands, probability mass), confidence word thresholds (clear/lean/split), near-call flags, strict 3.5 threshold, and tie-breaking order. It also clarifies that the org lens is a filter with no stored profile and that scores never change, directly addressing behavioral traits the annotation does not.

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 front-loaded with the purpose, then methodically explains the verdict system, confidence scoring, tie-breaking, and org lens. Every sentence is dense with relevant information. The bracketed free-tools note is slightly tangential but still useful context. It is long but justified by the tool's complexity, so only a minor deduction for the peripheral note.

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?

With no output schema, the description takes on the burden of explaining return value and behavior, and it succeeds. It enumerates all key output elements (scores, vendor options, AI replacement approach, action steps, banded verdict) and explains the verdict distribution, confidence words, and near-call logic. For a complex tool with nuanced behavior, this is fully 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?

Despite 100% schema description coverage, the description adds significant value. It explains the org lens in detail: what small/medium/large mean, how they shift the AI-feasibility band center (-1/0/+1), and reiterates that it is a read-time filter. This deepens understanding beyond the schema's enum descriptions, particularly the no-storage guarantee.

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+resource: 'Compare build vs buy for a specific software category.' This clearly states what the tool does and distinguishes it from siblings like b4_score (which scores) and b4_recommend (which recommends). The scope and output are also defined, so purpose is unambiguous.

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 establishes clear context: use this when you need a side-by-side build-vs-buy analysis with a banded verdict. It does not explicitly name alternatives or provide 'when not to use' exclusions, though it mentions free tools (b4_browse, b4_score) in a bracket note, implying some cost consideration. This is helpful but not a full usage guide.

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?

This description goes far beyond the readOnlyHint and openWorldHint annotations, disclosing the banded verdict methodology, ±1 uncertainty band, confidence word thresholds, near-call flag, tie-breaking order, strict 3.5 axis threshold, and the org lens's behavior as a read-time filter with no stored profile or user data. It also clarifies that scores never change, reinforcing the read-only nature.

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 front-loaded with a clear purpose statement, followed by logically organized methodological details, the org lens explanation, and a closing note about free tools. Most sentences add necessary information for correct invocation, though the bracketed note about b4_browse and b4_score is a slight aside.

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 and lack of an output schema, this description is exceptionally complete. It covers the return shape (top matches, scores, banded verdicts, actionable recommendations) and the nuanced decision logic (uncertainty bands, confidence words, tie-breaking, threshold strictness), leaving little ambiguity about the tool's behavior.

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 completely (description maxLength, org enum/default), so baseline is 3. The description adds meaningful context beyond the schema: it explains the org lens as engineering maturity (small/medium/large), the −1/0/+1 band shift, and notes that omitting it yields the published default-lens numbers. This enriches parameter understanding.

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's purpose: 'Get B4 Index recommendations from a natural language description of a software need or business context' and details the output (top matches with scores, banded verdicts, actionable recommendations). It names the specific resource and verb, but it does not explicitly differentiate from siblings like b4_compare or b4_audit, only mentioning that b4_browse and b4_score are free tools.

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 gives clear context for when to use the tool ('from a natural language description of a software need or business context') and detailed guidance on the org lens parameter, including what each value does and what happens if omitted. However, it does not explicitly state when not to use this tool or name alternatives for particular use cases.

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?

With readOnlyHint=true, the description adds substantial behavioral detail beyond the annotation: banded verdicts, ±1 uncertainty bands, confidence thresholds, near-call flags, tie-breaking order, and the org lens as a stateless filter that 'never stores a profile.' It also transparently explains the default lean result and the effect of includeEvidence. 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 information-dense. Every sentence adds unique detail about methodology, output contents, or option behavior, and the opening sentence front-loads the core purpose. The single-paragraph structure is somewhat heavy, but appropriate given the tool's complexity and lack of an output schema.

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 no output schema, the description enumerates the return components (banded verdict, confidence, near-call flag, full distribution, tipping point, axes, urgency level, breakdown) and explains the scoring methodology and option effects. This is sufficient for an agent to understand what it will get and how 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 baseline is 3. The description adds meaningful operational semantics: explaining that org shifts the AI-feasibility band by −1/0/+1, that scores are pre-computed or custom, and that includeEvidence returns the full research trail. This goes beyond the schema's structural 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 clearly identifies the action ('Score') and the resource ('a software category using the B4 Index'), and distinguishes two input modes: known category name or custom dimension scores. This differentiates it from sibling tools like b4_compare or b4_recommend by focusing on scoring rather than comparison or recommendation.

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 context on how to invoke the tool: use a known category or provide raw scores, optionally set includeEvidence and org. It also explains the org lens semantics. However, it does not explicitly state when to use this tool instead of the sibling tools, so it lacks explicit exclusion or alternative guidance.

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