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

Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) are complemented by rich behavioral disclosure: long-running call that may exceed client idle budget, atomic one-shot with no lifecycle, timeout behavior, retry budget implications, privacy/data-residency details, and rejection audit trail. 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 well-structured with clear section headers (WHEN TO CALL, BEHAVIOR, ELIGIBILITY GATE, PAYLOAD COMPLETENESS, etc.) and front-loads the critical recovery path. Every sentence adds information, though some redundancy exists (e.g., repeated mention of retry budget). Given the tool's complexity, this 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?

The description covers every aspect an agent needs to call correctly: eligibility gates, all typed rejection reasons with recovery actions, payload completeness rules with examples, authentication, data residency, and outcomes. The output schema exists and the description doesn't need to explain return values, but it explains all pre-LLM and post-LLM behaviors comprehensively.

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 description adds substantial meaning beyond the schema: it explains that `code` can be omitted under the 24h cert-retry hold, clarifies the SHA-256 fingerprint comparison, and details how `run_id` must be owned and sourced from a prior validate. This goes far beyond the schema's basic 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 states a specific verb (certify) and resource (architect.validate run), and clearly distinguishes it from the sibling architect.validate (first-pass vs second-pass adversarial certification). It also states the two possible outcomes (badge minted or downgraded to emerging), so an agent understands exactly what this tool accomplishes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'WHEN TO CALL' section: only after architect.validate returned tier=production_ready, user wants badge, and code untouched. It also states NOT to call for other tiers and gives the canonical recovery path (validation_history) on timeout, plus the re-validate workflow after code changes. Alternatives and exclusions are fully specified.

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 heavily supplements the annotations: discloses the long-running non-idempotent call (60-180s typical, retries re-run compute), recovery via run_id/validation_history, background task-augmentation, auth/plan gates, UK/EU residency, score variance, private-by-default URLs, and typed failures. Annotations (readOnlyHint=false, destructiveHint=false) are consistent — the tool persists runs — so no contradiction.

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 very long, but it is modularly structured with labeled sections (WHEN TO CALL, BEHAVIOR, INPUTS, PAYLOAD COMPLETENESS, SCORE VARIANCE, ITERATION LOOP, TYPED FAILURES) and front-loads the most critical operational hazard (timeout/retry/recovery). A few recovery details are repeated, but the density is largely justified by the tool's operational 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?

Covers every contingency an agent needs: timeout recovery, task-augmented invocation, auth/residency, payload completeness for certify intent, score variance disclosure, iteration chaining rules, verification layers, typed failures, and the next-step certify call. The output schema exists and the description still names key return fields without re-explaining the schema, making it operationally 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?

Schema coverage is 100%, but the description adds substantial operational meaning beyond the schema: implementation_context must be full verbatim content with explicit don'ts, repository is an iteration key whose alteration silently severs the chain, private_session disables persistence/recovery, and session_id has a pre-call ownership check. This is genuinely additive and load-bearing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+standard: 'first-pass doctrine review of agentic code/workflow against the 10-principle AI Design Blueprint doctrine.' It differentiates itself from siblings by explicitly naming architect.certify as the adversarial second pass and architect.validate_consensus as the variance-collapsing aggregate, so an agent can select among them without inspecting 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?

Has explicit WHEN TO CALL ('user wants a governance audit, readiness score, or production_ready badge on an agent/workflow') and WHEN NOT TO CALL ('non-agentic plumbing... returns tier=not_applicable... submit the OWNING agentic workflow instead'). It also routes to validate_consensus when stability matters and to certify for the badge, giving 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?

Annotations only signal a mutating, non-idempotent call, but the description discloses long-running 80-120s behavior, the do-not-retry rule, run_id emission timing, private_session persistence semantics (children not persisted, consolidated row is), auth/plan gate, and consensus-specific typed failures. This far exceeds annotation coverage.

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 and repeats a few facts (cost, private_session, n cap) across sections, so it is not maximally concise. However, it is well-structured with clear headers and front-loads the most critical operational warning (do not retry on timeout) before details.

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, expensive, long-running operation with an output schema, the description covers inputs, outputs, failure modes, auth, recovery, persistence, and downstream chaining. Nothing an agent needs to invoke or recover from this tool is left unexplained.

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 adds real value: it identifies n as the only extra arg, notes the server-side cap of 5 despite the schema max of 10, explains repository's role as iteration-key/baseline persistence, and stresses sending full file contents verbatim for implementation_context. It does not individually enrich every parameter, but the schema already covers those.

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 mechanism — running N parallel architect.validate calls and aggregating them into a per-principle mode verdict, median severity, stability, and score range/stdev — and names the return type (ConsensusValidationResponse). It also differentiates itself from architect.validate by framing consensus as the unanchored honest read versus single-shot baseline-anchored reassertion.

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 WHEN TO CALL and WHEN NOT TO CALL sections, including the concrete alternative (architect.validate) for iteration-delta needs. It further gives timeout recovery instructions and the chained validate → consensus → certify sequence, so an agent knows exactly when this tool is appropriate.

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?

Explicitly declares read-only, idempotent, no auth required, and notes assets are regenerated on every deploy. Adds value beyond annotations (readOnlyHint, idempotentHint) by stating no auth needed and regeneration behavior. 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?

Front-loaded with purpose, then enumerates response fields and usage guidance. Slightly verbose with parenthetical 'the full vocabulary' but generally efficient.

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?

No parameters, output schema exists, description covers response fields, behavior, and usage context fully.

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 has zero parameters with 100% coverage, so description need not add param info. Baseline of 4 for no-param 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 clearly states it lists downloadable asset artifacts (skill packs, rule packs, MCP setup snippets) and distinguishes from sibling tools like principles.list, clusters.list, and guides.list.

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 (user wants to import Blueprint as native files) and when not to call (for live MCP tools, prefer principles.list/get and guides.list/get).

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 that it is cacheable per slug and returns a 404 error on unknown slug requiring exact match, providing 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 well-structured with sections and contains no filler. Each sentence adds value, though it's slightly longer than 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?

With an output schema present, it does not need to explain return values. The description covers purpose, usage guidelines, error behavior, and exact matching requirements, making it complete for this 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% and the description clarifies that the slug must be a 'stable slug' and match exactly the value from clusters.list, adding useful nuance beyond the schema description 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 uses a specific verb ('Get') and resource ('principle cluster by stable slug'), and explains the return payload, distinguishing it from siblings like principles.get, clusters.list, and principles.search.

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 (user named a specific cluster, have slug from prior responses), when not to call (natural language topic -> principles.search; cluster discovery -> clusters.list; specific principle -> principles.get), and includes a warning against unnecessary loops.

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. The description adds what the output contains (stable slugs and linked principle titles), providing useful 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?

Three sentences, no wasted words: purpose, usage guidance, and alternative recommendation. Front-loaded with the action.

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 zero parameters, good annotations, and an output schema (not shown but indicated), the description fully covers what the agent needs: purpose, usage context, and output hint.

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; schema coverage is 100%. Baseline 4 applies as description adds no parameter info, which is appropriate given zero params.

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 "List all principle clusters" with a specific verb and resource, and distinguishes from siblings by mentioning clusters.get and filtering principles.list by cluster.

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 says when to use (discover clusters before drilling in) and when not to (prefer clusters.get when slug known), with alternatives named.

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 major behavioral traits: a long-running LLM call (60-180s), the DO-NOT-RETRY timeout rule, run persistence and run_id recovery, private_session disabling persistence, authentication/plan requirements, UK/EU residency and no-training processing, prompt-injection text being treated as inert data, typed failure envelopes, and a calibration caveat. This is far more than annotations alone provide and contains no contradiction with them.

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 well-organized into meaningful sections (purpose, timeout behavior, return semantics, when to call, inputs, auth, failures, calibration, doctrine). Each section adds operational information an agent needs. It is not maximally concise — some points repeat (not_applicable appears multiple times, session ownership appears in both schema and prose) — but it is front-loaded with the primary purpose and structured for scanning.

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 validator with 7 parameters, an output schema, and timeout/error behavior, the description is exceptionally complete. It covers return classification, per-law findings, readiness scoring, the accessibility production-blocker rule, auth requirements, failure types with retry guidance, recovery via run_id, and calibration limitations. Nothing an agent needs to decide whether to call and how to call 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 a baseline of 3 is appropriate. The description adds real value beyond the schema for the critical parameter implementation_context: it insists on verbatim full source, warns that '…' placeholders are read as literal code, and advises splitting large artefacts into multiple calls. It also clarifies repository grouping and session_id ownership rules, though those are largely repeated from 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 opens with a precise verb-plus-resource statement: 'first-pass surface-craft review of a FRONTEND artefact ... against the 8 laws of the Experience Design Blueprint.' It explicitly differentiates itself from architect.validate by contrasting 'agentic ARCHITECTURE' with the 'PERCEPTIBLE SURFACE,' and names the exact eight laws evaluated. An agent can immediately identify this as the design/UX-lens validator.

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 WHEN TO CALL ('craft/UX/accessibility review or readiness grade on a frontend artefact') and WHEN NOT TO CALL sections, including the non-visual-code not_applicable case and the pointer to architect.validate as the architecture counterpart. It also specifies the client-timeout recovery path (use me.validation_history with the run_id rather than retrying), leaving no ambiguity about selection or fallback.

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 read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail beyond those annotations: unknown slugs return error_payload, and certain entries carry extra conditional fields (pattern_slug, pattern_family, when_to_use, etc.) while others omit them. This is rich, non-redundant transparency.

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 earns its place: main behavior, return contents, usage routing, error behavior, and the conditional shape for pattern entries. It is front-loaded with the core action and structured so the conditional variant is clearly separated.

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 exists and annotations cover safety, the description is fully complete: it explains when to call the tool, what it returns, how errors manifest, and the conditional presence of extra fields. Nothing needed for correct invocation 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% and the single parameter slug is already documented with an example value. The description doesn't add parameter-specific semantics beyond what the schema provides, but with full coverage the baseline of 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 opens with a specific verb+resource ('Get one curated example by stable slug') and enumerates exactly what the response contains. It also explicitly differentiates from siblings by naming examples.search and guides.get, so an agent can select it without ambiguity.

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: use when the slug is already known from examples.search, principles.get, or a guide cross-link. It also states clear exclusions: prefer examples.search for filtering, prefer guides.get for full walkthroughs. This fully covers the selection logic.

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, so the safety profile is covered. The description adds substantial behavioral nuance beyond that: default limit 5 with server-side cap, inclusion of first-party agentic patterns (entry_kind='pattern') with doctrine binding, and a precise explanation of pattern relevance preference (never outranks a genuine failing-principle match, and 'depends' relation yields no match). This is rich, non-redundant context.

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 well-structured: purpose first, then filters, return fields, usage guidance, and behavioral notes. Every sentence adds information; there is no fluff or repetition. It is appropriately detailed given the tool's complexity (six parameters, multiple filters, cross-tool references). Not perfectly concise, but efficient for its scope.

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 has an output schema (not shown but indicated), the description need not explain return values. It covers all essential aspects: purpose, filters, usage alternatives, behavioral quirks (pattern preference, limit cap), and cross-tool linkage (slug hydrates via examples.get). Nothing an agent needs to call 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% (all six parameters have descriptions), so the baseline is 3. The description adds value by explaining the pattern_family filter implies patterns-only ('Filter to one family with pattern_family, which implies patterns only') and by summarizing the filter semantics in prose (principle_ids, difficulty, library). It also clarifies the limit is capped server-side. This goes slightly beyond the schema's own descriptions, justifying 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 opens with a precise verb+resource+method: 'Search curated examples by free-text query, ranked by relevance'. It also names the sibling tools it is not (examples.get, guides.search, principles.search), so an agent can immediately distinguish it from alternatives without inspecting 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?

Explicit usage guidance is front-loaded: 'Use this when the user describes a use case, technique, or library and wants matching examples' and then gives three concrete alternatives ('prefer examples.get when you already have the slug; prefer guides.search when the user wants a full walkthrough; prefer principles.search when the user wants doctrine guidance'). This is exactly the when/when-not/alternatives pattern.

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. The description adds 'Returns sections, action items, and linked principles,' which provides behavioral detail beyond annotations. 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?

Two sentences, no wasted words. The core action is front-loaded, followed by usage guidance. Every sentence 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?

Given the existence of an output schema (not shown but noted), the description covers all needed aspects: purpose, when to use, parameter guidance. No gaps for this simple getter 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 description coverage is 100% (slug parameter well-described). The description adds examples and notes the slug is 'stable', adding meaningful context beyond the schema. Baseline 3 with added value.

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 'Get' and the resource 'full application guide' with examples of stable slugs. It distinguishes itself from sibling tools like guides.list and guides.search by specifying the input (slug) and context.

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 provides when to use this tool ('when you already have the guide slug') and when to prefer alternatives (guides.search for natural language, guides.list for full inventory). No ambiguity.

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 provide readOnlyHint=true and idempotentHint=true; description adds context about guide topics (security, evaluation, observability), which is valuable 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?

Three sentences, each serving a clear purpose: purpose, usage, alternatives. 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?

With zero parameters, an output schema, and rich annotations, the description provides all necessary context for the agent to decide when and why to use this 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?

No parameters exist, schema coverage is 100%, so description is not required to add parameter info; baseline is 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 clearly states the verb 'List' and the resource 'application guides', and specifies the content areas (security, evaluation, observability) to distinguish from siblings.

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 use this tool vs alternatives: 'Use this to discover which guides exist before drilling in. Prefer guides.search when... Prefer guides.get when...'

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, indicating safe, non-destructive behavior. The description adds further behavioral context by specifying that the search matches against 'section answers and action items,' which is useful for understanding scope. No contradictions 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 two sentences long, with the first sentence stating the clear purpose and the second providing usage guidance and alternatives. No unnecessary words; every sentence adds value.

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 high schema coverage and an output schema present, the description covers purpose, usage guidelines, and sibling differentiation thoroughly. It is complete enough for an agent to correctly select and 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?

Schema coverage is 100%, so both parameters are already well-described in the input schema. The tool description does not add extra parameter details beyond what the schema provides, so a baseline score of 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 clearly states the action ('Search') and the resource ('application guides') with specific matching criteria ('section answers and action items'). It also distinguishes from sibling tools by mentioning 'guides.get' and 'guides.list', providing explicit 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 explicitly states when to use this tool ('when the user describes an engineering challenge...and wants matching guides') and provides alternatives for other scenarios ('Prefer guides.get when you already have the guide slug; prefer guides.list when you need the full inventory'). No ambiguity.

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 indicate non-read-only and non-destructive, but description adds write-only, single insert, side-effecting behavior, auth requirements (Bearer token, UK/EU residency), and confirmation response.

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 well-structured with sections, front-loaded main purpose, and every sentence provides value; slightly verbose but still efficient.

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 10 parameters with full schema coverage, existing annotations, and output schema, the description covers purpose, usage, behavior, auth, residency, and response completely.

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 3; description adds context by explaining engagement scopes and tying them to reason and support_type parameters, enhancing understanding beyond 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 the tool submits an agency engagement enquiry for a founder-led discovery call, lists engagement scopes, and distinguishes from siblings handoffs.partnership and handoffs.operator.

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 provides WHEN TO CALL and WHEN NOT TO CALL sections with alternatives, plus instructs to always confirm with user before firing.

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 context beyond annotations: write-only, single insert, side-effecting (creates visible ticket), auth requirements, and UK/EU residency. No contradiction with annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false).

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?

Well-structured with front-loaded key info, but moderately long. Sections like WHEN TO CALL and WHEN NOT TO CALL are useful. Slightly verbose but not wasteful.

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?

Complete for a handoff tool: covers purpose, usage guidelines, behavior, auth, residency, and response confirmation. Output schema exists (assumed) and description mentions return of ticket id + topic.

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 3. Description lists fields persisted but does not add significant semantics beyond the schema descriptions. Minor inaccuracy: mentions user_email not in schema, but overall adequate.

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 creates a support handoff record for human review, specifying the action (creates), resource (support handoff record), and context (when agent cannot resolve with read-only tools). It explicitly distinguishes from sibling tools handoffs.partnership and handoffs.agency.

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 when-to-call scenarios (user asks for human help, billing/access issues, tried doctrine tools) and when-not-to-call (proactively, silently, for logging, partnerships/agency). Also instructs to confirm with user before firing.

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 (readOnlyHint=false, destructiveHint=false) are consistent. Description adds: write-only, single insert, side-effecting, auth requirement (Bearer token), UK/EU residency, and response includes ticket id+audience.

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?

Well-organized with clear sections: purpose, when to call/not call, behavior. Every sentence adds value, no redundancy.

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 9 parameters (1 required) and annotations, description covers purpose, usage, behavioral traits, auth, locale, and response. Output schema exists but description mentions response shape. Complete 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 has 100% description coverage, so baseline is 3. Description does not add new parameter-level meaning beyond what schema already provides.

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 it creates a partnerships handoff record for design-partner, ecosystem, training, or advisory conversations. It distinguishes from sibling tools (handoffs.operator, handoffs.agency) by specifying use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-call: user explicitly wants to engage as a design partner, co-marketing/training partner, or evaluate Blueprint. When-not-to-call: for general support/billing/access (use handoffs.operator), paid-engagement (use handoffs.agency), or as a sales prompt. Includes confirmation instruction.

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 indicate readOnlyHint=false, and the description adds behavioral details: 'write-only, single insert', auth requirements (Bearer token), residency (UK/EU), and visibility scope (visible only to owning user). 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 well-structured with sections and front-loaded purpose, but slightly lengthy. Every sentence adds value, so it earns a high score.

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 3 parameters and an output schema, the description covers usage, behavior, auth, scope, and response details comprehensively.

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 description enriches parameters by explaining that notes record concrete observations, persistence as UserStageEvidence rows, and confirmation of stage_slug + course_slug in response.

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: 'append a free-text evidence note to a specific stage in the caller's active course.' It uses a specific verb (append) and resource (evidence note to a stage), and distinguishes from sibling tools like me.coaching_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, specifying that it should be called after concrete observations, not for intent or speculation, and not for every conversation turn. Also mentions pairing with me.coaching_context.

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 mark it read-only and idempotent, and the description goes beyond them with blocking semantics, at-least-once cursor delivery, best-effort wake-up, final confirming read before timed_out, rejection codes, and auth requirements. 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 text is long but carefully structured with labeled sections (THE LOOP, DELIVERY GUARANTEE, REJECTION CODES, Auth) and front-loads the blocking behavior. Minor redundancy exists between the opener's 'Pro/Teams' and the later Auth line, keeping it from a perfect score.

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 blocking, cursor-based polling tool, the description covers usage protocol, failure modes, delivery semantics, prerequisites, and auth. The existing output schema relieves it from describing return values, so nothing needed for correct invocation 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% and the parameter descriptions already document timeout clamping, cursor semantics, and session ownership. The description mostly refers the agent to those descriptions and adds only marginal behavior such as 'foreign session ids read as not found,' so it stays at the high-coverage 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?

Opens with a precise verb and resource: 'BLOCK until the session owner posts the next steer event to a Governed Session ... then return it.' This clearly differentiates await_steer from siblings like me.session_event (writes events) and me.sessions (lists sessions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit end-to-end loop (handoff -> await_steer -> ack -> execute -> handoff), retry behavior on timed_out, and preconditions such as team mode, owner scoping, and plan entitlement. This is stronger than merely naming a usage context.

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 'read-only, idempotent' and auth requirements, offering slight extra 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?

Description is well-structured with sections for WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR. Each sentence provides value, no redundancy.

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 explains the return value (thin_stages list with stage slug, course slug, missing principles, evidence_count, coaching_note). No gaps.

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 are defined, so schema coverage is effectively 100%. Baseline for 0 parameters is 4, and 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?

The description clearly states the tool returns 'stages in the caller's active course where recorded evidence is thin relative to the stage's principle requirements'. It uses specific verb and resource, and distinguishes from siblings like me.add_evidence.

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 provides when to call (e.g., 'what should I work on next') and when not to call ('to lecture the user on principles they have already satisfied; on every conversation turn'), plus pairing guidance with me.add_evidence.

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. The description adds complementary behavioral details: 'Auth: Bearer <token> (any plan, including basic)', 'read-only, idempotent', and lists return fields. While the annotations cover the core safety profile, the description enriches context with authentication requirements and return structure.

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 structured into clear sections (purpose, when to call, when not to call, behavior, auth, returns). It is front-loaded with the core purpose. Slightly verbose but not wasteful; every sentence adds value. A 4 reflects good conciseness and structure.

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 has no parameters, an output schema, and clear annotations, the description provides complete context: purpose, usage guidelines, behavioral traits, authentication, and return fields. It fully covers what the agent needs to correctly select and invoke this 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?

There are no parameters (0 parameters, 100% schema coverage). The description does not need to add parameter details. Baseline 4 is appropriate as no additional semantic value is required 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 the tool returns 'the caller's Blueprint learning-path state' with specific fields (current course slug, stage progress, certification status, etc.). It distinguishes from sibling tools like 'me.coaching_context' by its explicit purpose of answering 'where am I' and 'am I Capstone-eligible' questions.

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 explicit WHEN TO CALL scenarios (user asks 'where am I', 'what's next', 'am I Capstone-eligible', before suggesting next-step coaching) and WHEN NOT TO CALL (as a heartbeat, for another user's progress). This clearly guides the agent on appropriate invocation.

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 say readOnlyHint=false and destructiveHint=false, so the description carries the full burden of behavioral disclosure. The description richly discloses mutation behavior, the durable channel stamp, team-mode refusal, owner scoping, the 500-event limit, blank-summary refusal, and auth/plan requirements. It even enumerates exact rejection messages. No contradiction with annotations is present.

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 densely packed with actionable sections: channel provenance, requirements, event types, when to call, when not to call, rejection codes, and auth. The structure is clear and front-loaded with the core purpose. Some repetition exists (steer refusal appears multiple times), which costs a bit of conciseness, but every sentence carries real operational value.

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 write tool with sparse annotations and moderate parameter count, this description is complete: it covers prerequisites, permission model, failure modes, exact rejection strings, the sibling read-back path (me.sessions), and the relationship to me.await_steer. The output schema exists, so lack of return-value explanation is not a gap. An agent has everything needed 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?

Schema coverage is 100%, but the description adds meaningful semantics beyond the schema: event_type is tied to specific call scenarios, actor 'human' is explicitly reserved for the cockpit, summary is framed as 'a decision or transition, not a chat message', and session_id must be owned and team-enabled. The description also adds operational guidance like 'List sessions via me.sessions' and 'ack = started working on a steer'. This substantially exceeds the baseline for full schema coverage.

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: 'append a TYPED TEAM EVENT to a Governed Session's timeline'. It clearly distinguishes this tool from siblings by stating it posts the AGENT-SIDE vocabulary only)Skip steer/human events, and explicitly contrasts itself with cockpit-originated channels. An agent can immediately tell what this tool does and what it is not.

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 explicit WHEN TO CALL conditions: role handoffs, pushbacks, plan previews, gates, and acks, with a concrete ack workflow ('Post it FIRST on receiving a steer... then execute, then post handoff'). It also gives WHEN NOT TO CALL guidance: not a chat logainer never record a steer, and references the correct alternative (me.await_steer for receiving steers). Sibling routing is unambiguous.

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, destructiveHint. The description adds owner-scoping behavior ('ids you don't own answer Session not found'), error handling, and details on return structures for both modes. 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 is well-structured with a clear first sentence and enumerated modes. It is comprehensive but slightly verbose; however, all sentences contribute necessary context. It could be slightly shorter without losing clarity.

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 all necessary aspects: tool purpose, modes, input semantics, output structure, relationships to sibling tools, authentication, plan requirements, and error behavior. Given the complexity and the existence of an output schema, 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?

Schema coverage is 100% for the single parameter session_id, and the schema description is thorough. The tool description echoes this information but does not add significant new semantics beyond what is already in the schema parameter description.

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 that the tool lists or inspects the authenticated user's Governed Sessions, explaining that sessions are durable, owner-scoped containers grouping validation runs. It distinguishes two modes and implies the tool is distinct from siblings like me.validation_history and me.session_event by describing their relationships.

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 explains when to use each mode: no arguments to list all sessions, session_id to inspect a specific session. It also directs the agent to alternatives for fetching full run results (me.validation_history) and for attaching runs (pass session_id to validate tools). Auth and plan requirements are stated.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description explains behavioral details: returns Blueprint Readiness Score, letter grade, tier, and validator field; run_id returns persisted result_json; per-run authorization; and plan requirements.

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 somewhat lengthy but well-structured with clear sections for each mode. While every sentence adds value, it could be slightly more concise without losing clarity.

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 (three modes, three lenses, scores, auth requirements), the description is highly complete. It also mentions plan and authorization constraints, which are not covered by annotations or schema.

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 semantic value: explains the recovery use case for run_id, repository scoping, default behavior, and mutual exclusivity of run_id and repository.

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: returning validation run history for three lenses (architecture, design, spec) with three distinct lookup modes. It distinguishes itself from sibling tools like architect.validate by focusing on history retrieval, not execution.

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 usage guidelines are provided for each mode: run_id for recovering timed-out results, repository for per-repository trends with regression diff, and no arguments for per-repository summaries. It advises using modes (2) or (3) before re-validating to check regressions.

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, destructiveHint. Description adds that it returns error_payload on unknown slug, and explains the conditional fields per lens. This is 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?

Three sentences, front-loaded core purpose, no wasted words. Each sentence earns its place: purpose, parameter usage, and usage alternatives.

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 presence of an output schema (inferred), the description adequately lists returned fields and error handling. It covers all necessary context for an agent to correctly select and 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?

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining the lens selects which doctrine, gives example values, and notes that slug comes from principles.list. It also clarifies that return fields differ by lens.

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 'Get one doctrine entry by stable slug' and specifies the resource (doctrine entry) and verb (get). It differentiates from siblings by explaining when to use principles.search or principles.list instead.

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 provides when to use this tool ('when you already have the exact slug from principles.list') and when to prefer alternatives ('prefer principles.search when the user describes a topic...'). Also mentions default lens and error behavior.

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 behavioral context about lens selection and cluster filtering, but does not go into details like pagination or return size.

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 well-structured with the purpose first, followed by usage guidance. Every sentence adds value; no wasted words. It is appropriately sized for 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?

Given the availability of output schema and annotations, the description is complete. It covers tool purpose, parameter usage, and when to use alternatives, leaving no major gaps.

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 description enriches parameters by explaining the meaning of each lens option and providing concrete cluster slug examples, adding 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 it lists Blueprint doctrine with stable slugs, titles, and clusters. It specifies three lenses and uses precise verbs like 'List' and 'selects'. It distinguishes itself from siblings such as principles.search and principles.get.

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 advises when to use this tool ('full inventory' or filtering by cluster) versus preferring principles.search (topic/keyword) or principles.get (exact slug), providing clear decision 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 already mark readOnly and idempotent, but the description adds substantial behavioral detail: results are ranked by relevance, returns specific fields (title, cluster, definition, rationale, heuristics), lens behavior per doctrine, and eponym matching for laws (e.g., 'Hick', 'Fitts'). This goes well beyond the annotations and informs the agent of exact runtime behavior.

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 relatively long but every sentence serves a purpose: purpose, examples, return fields, usage guidance, lens explanation, eponym matching. It is well-structured, starting with core functionality then diving into specifics, and avoids redundant wording. A slight trim could improve, but it remains efficient for the information conveyed.

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 search tool with an output schema (not shown here), the description already covers return content, usage, and parameter behavior. It mentions ranked relevance and lens selection, covering likely agent needs. It does not discuss pagination or error handling, but the schema mentions the limit cap, and such details are minor. Overall, an agent can call this correctly without missing critical information.

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 each parameter described, so baseline is 3. The description adds value by giving query examples, clarifying lens values with doctrine counts and defaults, and mentioning the limit is capped at server maximum (though schema already says that). It enriches understanding of how parameters affect results beyond the schema text.

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 searches Blueprint principles by free-text query and returns closest matches ranked by relevance, with concrete examples ('reversibility', 'approval flow'). It clearly distinguishes itself from principles.list by specifying when to prefer this over listing all principles, so an agent can differentiate it from sibling tools without opening 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?

It gives direct guidance: 'Prefer this over principles.list when you have a specific topic in mind rather than wanting all principles.' It also provides typical use cases (design challenge, failure mode, keyword) and explains the lens parameter selects the doctrine, giving explicit when-to-use vs alternatives. No ambiguity remains about when to invoke this tool.

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. It discloses that the tool is write-only and open to all callers, stores data under UK/EU residency, only stores contact_email when permission_to_follow_up=true and confirms that back to the user, opens a support inbox item and sends free-text to OpenAI for triage only under specific conditions, and explicitly says personal data must stay out of free text. This is rich, actionable behavioral disclosure.

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 well-structured with clear sections (purpose, when to call, when not to call, behavior). It is front-loaded with the core purpose and each sentence adds necessary information. No fluff; every detail about privacy and data handling 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?

Given the complexity of 9 optional parameters and the presence of an output schema, the description covers all essential aspects: when to call, privacy boundaries, data residency, external processing, and the distinction from signals.report. Nothing an agent needs to correctly invoke the tool is missing. The output schema handles return values, so the description need not explain them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the conditional relationship between permission_to_follow_up and contact_email, and by warning to keep personal data out of free text. It also clarifies that category is captured, though the schema already lists it. This is more than the schema provides, so a 4 is warranted.

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 ('records') and a specific resource ('explicit free-text user feedback about the Blueprint, this tool surface, or a specific principle/example'). It also explicitly differentiates from the sibling signals.report by saying 'Use signals.report instead for value-moment metrics', so an agent can distinguish between the two without opening 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 contains explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections. It specifies that the tool should only be called when the user explicitly requests feedback, gives concrete examples, names the alternative (signals.report) and the condition for it, and warns against proactive or silent use. This is unambiguous 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?

Discloses write-only nature (single insert), auth requirements (Bearer, Pro/Teams, UK/EU), and constraints (no PII/code stored). Annotations are all false, so description carries full burden and does so thoroughly.

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?

Well-structured with sections but somewhat lengthy. Could be tightened, but front-loads key info and has clear organization.

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 7 parameters, output schema present, and complexity of usage, the description covers all necessary aspects: when/why, behavior, auth, constraints. No gaps.

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 detailed parameter descriptions. Description provides general context but does not add significant meaning beyond 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 defines the tool as recording a 'value moment' after a successful validate run or doctrine session, specifying example event types and contexts. It clearly distinguishes from sibling tools like signals.feedback.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes explicit WHEN TO CALL (after validate with user acknowledgment) and WHEN NOT TO CALL (silently, every validate, speculative) sections. Does not explicitly name sibling tools, but provides clear context.

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 annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) are far exceeded by the description's operational disclosures: the 60-180s single-pass runtime, the client-timeout protocol (DO NOT RETRY; capture run_id from the first progress event and fetch via validation_history), persistence semantics via private_session, typed failure envelopes, auth/plan requirements, UK/EU residency and no-training data handling, prompt-injection inertness, and the calibration disclosure that the v1 scorer is not yet tuned. Every claim is actionable.

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 well-organized and front-loaded: purpose and sibling differentiation lead, followed by the timeout protocol, return semantics, when-to-call, inputs/auth/failures, and calibration. Some density could be trimmed — the GEP-M2 session detail substantially duplicates the schema's own explanation — but the operational complexity justifies the length overall.

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 7 params, no enums, a rich output schema, and complex operational behavior, the description covers the full lifecycle: preconditions (auth/plan), invocation (verbatim spec input), failure handling (typed failures plus the timeout recovery flow), and result semantics (spec_classification, not_applicable routing, shared scoring rubric, readiness grade). The output schema covers return values, so the description correctly summarizes rather than repeats 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 3 baseline applies; the description then adds genuine value beyond the schema. It mandates sending implementation_context verbatim with no truncation or '…' placeholders, specifies how to concatenate OpenSpec change bundles, explains that repository groups runs under the 'spec' dimension, and ties the run_id recovery protocol to the persistence behavior controlled by private_session. The no-truncation warning is load-bearing and absent from 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 precisely that the tool performs a first-pass specification-quality review of a WRITTEN SPEC against the 8 laws of the Spec Quality Blueprint, with an explicit three-way differentiation from siblings: architect.validate scores built agentic ARCHITECTURE, design.validate scores the rendered SURFACE, and spec.validate scores the written intent. Scope is unambiguous — the what-to-build lens applied before code exists.

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?

Contains explicit WHEN TO CALL and WHEN NOT TO CALL sections: call when the user wants a governance/quality review or readiness grade on a spec; do not call on built code or a rendered surface, which return tier=not_applicable. It also names the alternatives (architect.validate, design.validate) and routes non-spec inputs like source code or UI artefacts to the correct siblings.

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, idempotent, and non-destructive. The description adds depth: it names the data sources (AIToolCallLog, ValueEvent, AIValidationRunLog), explains that private_session bypasses only the read logging while historical data persists, and notes plan/residency restrictions (Teams only, UK/EU). 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 longer than a one-liner but structured with clear headings (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and front-loaded purpose. Every sentence earns its place; the verbosity is justified by the tool's complexity and the need to clarify plan restrictions and private_session semantics.

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 read-only aggregation tool with an output schema, the description covers the core question triggers, exclusions, data sources, authentication and plan requirements, and the private_session edge case. Nothing an agent needs to decide or execute a call 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 description coverage is 100% and both parameters (days_back, private_session) are fully described in the schema with defaults and purpose. The description re-echoes the window default but adds no new meaning beyond what the schema already provides, so baseline 3 applies.

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 ('summarises') and resource (caller's tool-usage patterns and value signals) with configurable window and default. It clearly distinguishes this tool from all siblings by describing the unique aggregation and output fields, so an agent can tell it apart without opening 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?

Explicit WHEN TO CALL and WHEN NOT TO CALL sections give concrete trigger phrases ('how is the Blueprint helping me/my team') and exclusions (proactive use, every turn, comparing users). This is model guidance for tool selection.

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