aibvf-mcp

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

Even though the annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, the description expands with specifically missing behavior: missing pillars are estimated deterministically and reported, unresolved inputs become issues with suggestions, all defaults appear in assumptions, no hidden business judgements happen, and no state or side effects exist. It not only matches but strengthens the annotation profile.

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 its length is justified by rich behavioral content. The first sentence defines the resource and guarantee; the middle lists transformation and outputs; the end declares safety and side effects. It is front-loaded with the decision-relevant sentence and every subsequent sentence adds a distinct capability or constraint. No filler is 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?

Toward an the agent needs to call this correctly: inputs, what gets resolved, what gets estimated, where those estimate appear, that validation happens, unresolved inputs return issues, and that no state/network/auth are involved. An output schema already covers the return shape, so the description need not repeat it. The context is complete for the tool's complexity.

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 itself documents organization, initiatives, defaults, and the rule against inventing scores. The description adds a better user-facing summary for 'pass only the numbers the user gave you' and 'unresolvable inputs come back' but most of that is already true in the schema. It gives useful framing, but no new type-level or format-level semantic.

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: 'Assemble a valid AI BVF v1.0 portfolio document from loose inputs, deterministically.' It immediately separates the tool from producers of individual scores or continuous operations like sequence_portfolio and validates, and from sibling tools by stating that it resolves aliases same as map_to_taxonomy and builds what later portfolio tools need.Product.

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 explicitly says 'CALL THIS when the user lists several AI initiatives in conversation and you need a portfolio document for validate_portfolio, score_portfolio or sequence_portfolio, instead of composing the JSON by hand.' It also gives an explicit exclusion: do not invent pillar scores; pass only evidence-based numbers. This is almost optimal routing guidance, including cautionary instructions.

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 annotations with behaviors like "Pure deterministic calculation, no network, auth or side effects." It also reveals key logical rules, including that missing work architecture blocks Accelerate, unresolved values are never guessed, estimated pillars reduce confidence, and a fully-estimated pass can never return Accelerate. This is materially richer than the readOnlyHint/idempotentHint/destructiveHint 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 dense but every sentence earns its place. It front-loads the primary call condition and purpose, then covers behavioral constraints, sibling routing, evidence handling, and final safety guarantees. For a tool with 9 parameters and significant decision logic, this length is justified and well structured.

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 explains invocation timing, candidate context, missing-data handling, the effect of evidence gaps, verdict conditions, and determinism. Since an output schema already exists, the description does not need to itemize return fields. There are no obvious situational gaps left for an agent deciding whether and how to invoke the tool.

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?

Even though the schema already covers 100% of parameters in high detail, the description adds critical usage semantics around those parameters: pass only pillar scores with real evidence, do not invent numbers, call with whatever the user gave, then re-call with evidence. It further explains that work architecture fields should only be true when the design has actually been redesigned, which directly improves correct field-set selection.

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 explicitly names the tool as "the front door for one AI investment decision" and says "CALL THIS FIRST" when the user describes an AI idea in ordinary language. It clearly separates this tool from its siblings by naming exact alternatives (score_initiative, score_portfolio, diagnose_process). This gives the agent an unambiguous actionable purpose with no need to parse 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 description gives explicit when-to-use conditions: "when user describes an AI idea in ordinary language or asks whether it should proceed." It also provides clear alternatives: "Use score_initiative when canonical fields are already known, score_portfolio for several initiatives, and diagnose_process for measured waste in a running process." This is Specific and direct usage routing.

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?

Description discloses deterministic calculation with no side effects, no network or auth, consistent with annotations. Adds context about return format and pure calculation 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?

Comprehensive single paragraph, front-loaded with purpose, but could benefit from structural breaks for readability. No wasted 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?

Covers purpose, usage, parameter behavior, return values, and safety. Output schema exists but description adds essential context about deterministic nature and no side effects.

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?

Adds meaning beyond schema by explaining how parameters interact (e.g., gen3+silod costs more), scaling with revenue, and future placeholder for industry.

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 quantifies annual EUR cost of AI ambition outrunning operating model, explicitly distinguishing from siblings like score_initiative, diagnose_process, and recommend_improvements.

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?

Explicitly states when to call ('cost of waiting for the organisation to change'), when not to use, and provides alternative tools for other needs.

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 and idempotentHint=true. The description adds 'Pure deterministic calculation — no network, auth, or side effects,' which reinforces safety and explains output behavior (e.g., 'signal_completeness must fall when inputs are estimated'). No contradictions; adds useful context 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 front-loaded with a clear summary, then elaborates on parameter usage and trade-offs. While dense and slightly long, every sentence adds value; no wasted words. Could be slightly more concise but well-organized.

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 13 parameters, 11 required, 100% schema coverage, and an existing output schema, the description thoroughly explains the tool's logic, constraints, and output components (intervention, savings, confidence). It is fully complete for a complex process diagnosis tool.

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%, but the description greatly enhances meaning by explaining how parameters interact (e.g., 'instances_per_year × fte_hours_per_instance × loaded_hourly_rate_eur builds the labour baseline') and how friction signals select interventions, thereby providing significant value 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 clearly states what the tool does: 'Diagnose a single existing business process from operational evidence and return the intervention, modelled net EUR saving, efficiency gain, verdict and confidence.' It specifies the verb (diagnose), resource (process), and output, distinguishing it from siblings that focus on portfolios or initiatives.

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 guidance: 'CALL THIS when the user can describe a process already running...' and explains when not to use it, directing to alternatives like 'score_initiative' for AI investment and 'infer_readiness' for change capacity, thus providing clear contextual differentiation.

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, and destructiveHint=false. The description adds extra behavioral detail beyond that: the lookup is deterministic, requires no network or auth, and produces an unadjusted or adjusted rate rather than a verdict or business case. It also clarifies the relationship of external research to this tool, which helps the agent reason about naming and expectations.

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 core purpose and explicit call signal, then moves from parameter semantics to output clarification, alternatives, and technical behavior. Some detail is present, but every sentence contributes either a necessary constraint, a clarification, or an alternative. The structure is efficient for agent parsing.

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 two enum-constrained required parameters, an output schema, and overlapping sibling tools, the description is complete. It tells the agent when to use the tool, what the output is not, how to understand the function and industry parameters, and what behavior to expect. Nothing material 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?

The input schema already documents both parameters at 100% coverage with enum values and descriptions. The description restates the function/industry relationship without materially adding new semantics: function selects rate ranges and drivers, industry applies a multiplier, and universal returns the unadjusted base. This is helpful reinforcement, but the schema is doing the heavy lifting, so a mid-range score is appropriate.

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: 'look up the disclosed AI BVF planning rates... for one business function and industry.' It clearly defines what the tool returns — a rate as a fraction of revenue — and distinguishes it from scoring and portfolio tools by stating what it is not. This makes the tool's purpose easy to separate from all sibling 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 explicitly says 'CALL THIS when the user wants to inspect revenue-uplift and cost-takeout assumptions before scoring, or to compare value drivers across functions.' It also gives direct alternatives: use score_initiative for verdicts, score_portfolio for multiple initiatives, and diagnose_process for measured operational waste. This is far beyond the threshold of minimal viability.

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 readOnly, non-destructive, idempotent. The description adds genuinly useful 'pure determininitic calculation, no network, auth, or side effects', the no-guess refusal, and the confidence effect of signal disagreement. Strong extra behavioral context 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?

Dense and front-loaded: starts with purpose, then scheduling, then parameter context/closing behavior and safety. It is a good-size paragraph and every sentence contributes; the only minor downside is slight overlap with the claimed_readiness schema text.

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 deterministic readiness calc, with rich param descriptions, an output schema, and annotations already carrying safety profile, the definition adds enough decision rules, input condition, refusal behavior, and workflow. There is no obvious gap an agent would need filled.

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?

Since input schema already fully describes all 7 parameters with concrete thresholds and enums, the bar is lower. The description still adds meaning about function as median-selector, claimed_readiness purpose, signal-count interaction confidence, and disagreement relation, going beyond the schema is a worthwhile way.

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?

Opens with a concrete verb and resource: 'Measure organisational readiness from process data'. It distinguishes itself from siblings by naming where it slots in the workflow, before score_initiative/score_portfolio/calcucalate_pace_layer_drag and before diagnose_process for follow-up.

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?

Gives explicit when: 'CALL THIS before ... when the user can provide at las two of five signals'. It also tells the agent the refusal behavior with fewer than two and states when to pass claimed_readiness, so the choice condition is fully operational.

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?

Description adds behavioral details beyond annotations: 'Pure deterministic lookup — no network, auth, or side effects' and 'Takes no parameters', consistent with readOnly and idempotent hints.

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 concise, front-loaded sentences that cover purpose, usage guidance, and behavioral notes with no wasted 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?

Given no parameters and an existing output schema, the description fully covers what the tool returns (taxonomy only, no score/verdict/language mapping) and its deterministic nature.

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, and schema coverage is 100%. Description confirms 'Takes no parameters', meeting the baseline expectation of clarity for zero-parameter tools.

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 explicitly states it returns 'exact industry, function, AI-tier and readiness values' and distinguishes itself from map_to_taxonomy, which is a sibling tool.

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?

Describes when to call this tool ('when the caller needs the complete allowed list or when a free-text value is not obvious') and explicitly names the alternative map_to_taxonomy for specific term lookups.

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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds 'Pure deterministic lookup, no network, auth, or side effects' and explains null result behavior. This enriches transparency beyond structured fields.

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 paragraphs with a clear first sentence summarizing purpose. It is well-structured and front-loaded, though slightly verbose. Every sentence adds value, so it earns a 4.

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 an output schema exists, the description appropriately focuses on usage behavior. It covers return value structure, null handling, and side-effect-free nature. Context is complete for this complexity level.

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 baseline is 3. The description adds value by explaining that parameters are free text and describing the return structure (canonical value, match, or null with suggestions). This goes beyond the schema 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 states the verb 'Map' and the resource 'everyday business language to the canonical AI BVF values'. It distinguishes from sibling tools like list_taxonomy and the scoring tools, making the purpose 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?

Explicitly tells when to call this tool ('when the user says... and the matching enum is not certain') and when to use list_taxonomy instead. Also directs to pass mapped values into specific tools, providing clear alternatives.

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 discloses meaningful behavioral internals beyond the annotations: omitted diagnostics remain provisional, missing pillars are estimated and enshrined as marked provisional, a next question is returned, and it is a "pure deterministic calculation, no network, auth or side effects." It also explains treatment of resistance_type and risk_type route selection, and highlights how previously estimated pillars require re-calling.

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?

Every sentence expands the invocation contract: what it produces, when to call it, when not to call it, interplay between optional diagnostics, and execution nature. It is dense but not inflated; the first sentence states the purpose, and later sentences give operational and exclusion rules without padding.

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 a fully described input schema, an output schema exists, and the description addresses the conditional workflow, the same-case requirement, missing values, and the route selection mechanisms, no critical guidance gap remains for an agent to invoke it correctly after scoring.

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 covers 100% of parameter semantics in detail, so this could be baseline 3. The description adds value by tying parameters to the orchestration contract: "same five context fields", "scores and work-architecture evidence from that call", and the interaction of optional diagnostics with route selection. It also adds explicit guardrail: omitted diagnostics remain provisional with the next question returned.

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: "Turn a Fix or Stop verdict into the change plan that could earn a re-score," and enumerates concrete outputs (pillar targets, named plays, owners, stop conditions, cost of waiting, deadline). It clearly differentiates from siblings by saying do not use it for initial verdict, sequencing, or process diagnosis jobs that belong to score_initiative, sequence_portfolio, or diagnose_process.

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 gives an explicit when-to-use condition — "CALL THIS after score_initiative returns Fix or Stop, using the same five context fields" — and explicit when-not-to-use exclusions with named alternatives. It also warns against calling for Accelerate unless a specific delivery risk needs testing before commitment, which is unique and essential routing 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?

Beyond the annotations, the description discloses that the calculation is 'pure deterministic, no network, auth or side effects,' that missing pillars are estimated deterministically rather than invented, and that a fully estimated pass can never return Accelerate. This substantially enriches what an agent can infer from annotations alone, without contradicting any annotation.

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 longer than average, but every sentence carries weight: usage conditions, alternative tools, pillar-estimation behavior, return value summary, and safety characteristics. It is efficiently structured with the primary use case and verdicts 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?

With 8 parameters, four nomenclature-specific fields, an optional nested object, a known output schema, and a large sibling-tool set, the description supplies enough context to select and invoke the tool correctly and to route to the appropriate alternative, and further notes 'No network, auth or diversity side effects'.

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?

Parameter schema description coverage is 100%, so the baseline falls at 3. The description adds high-level guidance about not inventing pillar scores and re-calling with evidence, but the per-parameter meaning is already covered comprehensively by 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 states a specific verb and resource: it is a 'Canonical-field scorer for one AI initiative.' It further distinguishes itself by identifying the exact inputs required, the verdicts returned, and explicitly names alternatives such as assess_ai_initiative and score_portfolio.

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 is explicit about when to use it: 'CALL THIS when industry, revenue_eur, function, ai_tier and readiness are already known, or when re-scoring with measured pillar evidence.' It likewise tells the agent to call assess_ai_initiative first for ordinary business language, score_portfolio for several initiatives, and diagnose_process for measured waste — providing a complete decision rule.

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 establish readOnly, idempotent, and non-destructive behavior, but the description adds valuable nuances: 'skipped, never silently counted' for missing revenue/invalid taxonomy, the single readiness value applying portfolio-wide, and 'pure deterministic calculation — no network, auth, or side effects.' This adds real behavioral context beyond what annotations alone provide.

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 core purpose and output, then flows into when-to-use, behavioral caveats, sequencing, and safety properties. Every sentence contributes non-redundant information for a complex tool, and there is no filler or repetition.

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 output schema covers return values and the input schema covers parameter details, the description completes the picture with preconditions, skip behavior, integration with sibling tools, and a deterministic/read-only safety profile. An agent has everything necessary to select and invoke this 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?

The schema already provides 100% coverage of both parameters, including nested portfolio structure and readiness enum meanings. The description reinforces key constraints like organization.revenue_eur being required and readiness applying uniformly, but it doesn't substantially add new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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 states a specific verb and resource ('Score several AI initiatives as one AI BVF v1.0 portfolio') and enumerates the return outputs: counts, EUR value range, mean confidence, highest-value/highest-risk initiative, and individual results. It explicitly distinguishes itself from looping score_initiative and references related tools like validate_portfolio and sequence_portfolio, giving clear sibling differentiation.

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 explicit when-to-use guidance: call when the user has a portfolio and needs to know its contents before funding/order decisions, rather than invoking score_initiative repeatedly. It also provides conditional routing: use validate_portfolio first only when document shape is uncertain, and use sequence_portfolio when a 90-day order is needed. This goes well beyond a basic 'when to use' statement.

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 adds meaningful behavioral context beyond the annotations: it explicitly states the tool is a pure deterministic calculation with no network, auth, or side effects, and that capacity overflow is never hidden but reported as a conflict or deferral. It also clarifies it does not mutate or re-score anything. Nothing contradicts the readOnly, idempotent, or destructive 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 dense but each sentence earns its place. It front-loads the critical call placement ('CALL THIS after score_portfolio'), gives the essential scope, then covers inputs and behavior without repetition or 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 complex tool with nested inputs and five parameters, the description covers required input types, valid alternative input shapes, constraint behavior, overflow semantics, and integration with recommend_improvements. An output schema exists, so return-value details are not needed in the description. The context is complete enough for an agent to invoke it correctly without ambiguity.

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?

Although schema coverage is 100%, the description adds high-level semantic guidance that the schema alone doesn't provide: pass the output of score_portfolio directly into portfolio, or use organization plus initiatives; readiness sets capture rates and pacing; horizon_days splits the plan into three equal windows; and max_parallel_per_function caps simultaneous change per function per wave. This helps the agent make correct invocation decisions quickly.

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—turn a scored AI portfolio into three waves with gates over a configurable horizon—and clearly states what it does not do: it does not change verdicts or re-score the business case. It also distinguishes itself from score_portfolio and recommend_improvements by positioning the tool's role in the workflow.

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 explicitly says 'CALL THIS after score_portfolio when the user asks what to stop, fund first, defer or fit into the next 90 days.' It also names recommend_improvements as a required prerequisite for Fix initiatives before wave placement is treated as permission to proceed, so the agent receives concrete when-to-use and when-not-to-proceed 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?

Disclosure goes beyond annotations: states it is 'pure deterministic validation — no network, auth, or side effects', explains what it does not do ('does not judge the evidence or calculate a verdict'), and clarifies valid pillar shapes. 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?

Description is concise, well-structured, and front-loaded. Every sentence adds unique value without repetition or fluff. The first sentence immediately states purpose and 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?

Given input schema details, output schema existence, and lack of output schema shown in input, the description covers validation behavior, return format (valid=true or errors), and scope. No gaps remain for the agent to select and invoke 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%, but the description adds significant value: explains the portfolio document structure (bvf_version, organization, initiatives array), the validation scope (required fields, taxonomy, ranges), and the acceptable score shapes (bare number or object). This exceeds schema 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 states the tool validates an AI BVF v1.0 portfolio document with the verb 'check' and resource 'shape'. It explicitly distinguishes from siblings by naming assemble_portfolio, score_portfolio, and sequence_portfolio with their specific use cases.

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 explicit guidance: 'CALL THIS when the document came from a file, another system or hand-built JSON and its structure is uncertain.' Also specifies when to use alternatives (assemble_portfolio, score_portfolio, sequence_portfolio), giving clear when-not-to-use context.

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