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

Annotations already indicate non-readonly, non-idempotent, non-destructive. The description adds: atomic one-shot LLM call exceeding typical idle timeout, first event carrying run_id, state mutation (badge mint/downgrade), and eligibility gate enforcing retry budget and fingerprint checks. 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?

Well-structured with sections and front-loaded critical recovery path, but overly verbose with repeated concepts (e.g., recovery path mentioned multiple times). Could be more concise while retaining completeness.

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 high complexity (rejection reasons, eligibility gates, payload completeness, recovery paths, budget constraints), the description is exceptionally complete. All necessary context for correct invocation is present.

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

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

Schema coverage is 100%, baseline 3. Description adds: code can be omitted if stored under 24h hold; run_id must be own validate run_id. Explains interaction between parameters and server behavior, providing context beyond 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 defines 'second-pass adversarial certification' of an architect.validate run that scored production_ready. It clearly distinguishes from sibling tools (e.g., architect.validate) and uses specific verb+resource: 'certify' a run by minting a badge or downgrading.

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 (only after validate returned production_ready, code unchanged), when not to call (wrong tiers, code modified), and provides canonical recovery path on timeout via me.validation_history. Also warns against retrying due to budget consumption.

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, which only indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. It explains the long-running nature (60-180s typical, 20-min budget), run_id minting at t=0, keepalive, persistence, auth requirements (Bearer, Pro/Teams), residency (UK/EU), OpenAI processing (no-training), and that prompt-injection is inert. It also discloses score variance and reproducibility mode. 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 extremely long (multiple dense paragraphs) and includes verbose details like task-augmented invocation protocol, verification layers, and historical PR references. While valuable, it could be more concise: the MCP task protocol details and the two-layer verification explanation could be moved to separate documentation or skill references. The sheer length risks overwhelming the agent and obscuring key points.

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 (10 parameters, output schema, multiple sibling tools), the description is exceptionally complete. It covers recovery on timeout, iteration loops, relationship with certify and consensus, variance disclosure, input rules, and even edge cases like rollback behavior. The output schema exists, so return values are not needed in the description. The description leaves no critical gaps for an agent to effectively use 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?

Despite 100% schema description coverage, the parameter descriptions add significant context beyond the schema. For example, it explains that `implementation_context` must be full verbatim (no truncation), `repository` is an iteration key with anchoring semantics, `private_session` disables logging and recovery, and `session_id` requires ownership check. The description also warns about common pitfalls like splitting files correctly and using `focus_area`.

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 performs a 'first-pass doctrine review of agentic code/workflow against the 10-principle Agentic AI Blueprint'. It distinguishes from siblings like architect.certify, architect.validate_consensus, and me.validation_history by explaining the role of validate vs certify vs consensus, and the recovery path. The verb 'validate' is specific and the resource 'agentic code/workflow' is well-defined.

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 (user wants governance audit, readiness score, or production_ready badge) and when-not-to-call (non-agentic plumbing returns tier=not_applicable). It also details recovery on timeout via me.validation_history, and warns against truncating input. Additionally, it guides on iteration loop with repository keying and when to use architect.validate_consensus for stable results.

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, openWorldHint=true, etc. The description adds extensive behavioral context: timeout duration (80-120s), retry prohibition, recovery pattern via validation_history, parallelism and cost (N× LLM), auth requirements (Pro/Teams), private_session behavior, and typed failures including consensus-specific. This far exceeds 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?

Despite length, the description is well-structured with clear sections: timeout warning, when-to-call, behavior, auth, inputs, outputs, failures. Every sentence is informative and earns its place. Front-loaded with critical retry instruction.

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 tool complexity (9 params, sibling set, annotations, output schema exists), the description covers all necessary aspects: purpose, behavior, constraints, usage guidance, interaction with siblings, error types, and output fields. No gaps noted.

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%, so baseline is 3. The description adds value beyond the schema by explaining the role of parameters in the consensus context (e.g., 'n' capped server-side, 'repository' as iteration key, 'implementation_context' requiring full content). This extra context justifies above baseline.

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

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

The description clearly states it performs an 'N-shot CONSENSUS doctrine review of agentic code', distinguishing itself from the sibling architect.validate by explaining that the single-shot version re-asserts prior baselines while consensus provides an unanchored honest read. The verb 'validate' is combined with 'consensus' to specify the unique approach.

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' (honest first-pass score with variance surfaced) and 'WHEN NOT TO CALL' (when iteration delta needed, use architect.validate) sections provide clear guidance. Also includes chain resume sequence and references the full orchestration skill.

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?

The description discloses many behavioral traits beyond annotations: long-running (60-180s), client timeout handling with run_id and persistence, private_session option, typed failures, calibration disclosure. Annotations are minimal (readOnlyHint false, etc.), but description compensates fully.

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 and covers many details, but it is well-structured with clear sections (e.g., DOCTRINE, WHEN TO CALL, TYPED FAILURES). Some redundancy exists (e.g., listing the 8 laws in detail and referencing them later), but overall it is organized and front-loaded with core purpose.

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 (7 parameters, output schema, long-running behavior, error handling, recovery, calibration), the description covers all needed information. It explains return values (surface_classification, per-law findings, etc.), even though output schema details aren't provided here.

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 description adds substantial meaning: explains why implementation_context must be full source, how repository groups runs, session_id ownership check, private_session persistence details. Each parameter's role is enriched beyond the schema 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 the tool is for 'first-pass surface-craft review of a FRONTEND artefact against the 8 laws of the Experience Design Blueprint' and distinguishes from architect.validate which scores agentic architecture. The verb 'validate' and resource 'design' are clarified with specific scope.

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 provide clear context: call when user wants craft/UX/accessibility review on a frontend artefact, not for non-visual code. Alternatives like architect.validate are named for architecture reviews.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds value by stating that an error_payload is returned on unknown slug, which is useful error-handling context. 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 concise with three sentences, each serving a purpose: stating the action, listing fields, and providing usage guidance. No fluff.

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 only one parameter and an output schema is present, the description covers all necessary aspects: what it does, what it returns, and error behavior. 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%, baseline 3. The description adds an example slug ('agents-building-blocks-5-control') and clarifies it's a 'stable slug,' which enhances understanding beyond the schema 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 the tool gets a curated example by stable slug and lists the returned fields. It explicitly distinguishes from siblings examples.search and guides.get, 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?

The description provides clear when-to-use guidance (when slug is known) and explicitly directs to alternatives: examples.search for filtering, guides.get for walkthroughs. This effectively prevents misuse.

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. The description adds return fields, relationship to examples.get via slug, default limit 5, and server-side cap, which are useful 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?

Single paragraph, front-loads core purpose, then details filters, return fields, and usage guidance—every sentence earns its place without waste.

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 (multiple optional filters, output schema), the description fully explains inputs, outputs, and relationship to other tools, making it completely informative.

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 descriptions. The description adds context for filters (e.g., principle_ids, difficulty, library) and default limit behavior, providing extra 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 states the tool searches curated examples by free-text query with ranking, and distinguishes it from siblings like examples.get, guides.search, and principles.search, providing specific verb and resource.

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 on when to use (user describes a use case, technique, or library) and when to prefer alternatives (examples.get for known slug, guides.search for walkthrough, principles.search for doctrine), leaving 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 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?

Discloses behavioral traits beyond annotations: read-only nature, idempotent delivery (at-least-once), wake-up mechanism, and that timed_out is only returned after confirming read. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all align).

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 long but well-structured with labeled sections (DELIVERY GUARANTEE, THE LOOP, REQUIRES, REJECTION CODES). Each sentence adds necessary detail for correct usage. Could be slightly shorter, but complexity justifies length.

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 core loop, error cases, delivery guarantees, and parameter semantics. With output schema present, return values need not be described. Addresses prerequisites (team mode, ownership). Lacks examples of output or edge cases, but overall sufficient for a complex 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 description adds substantial value: explains timeout default relative to Claude Code timer, session_id ownership and team mode requirement, after_event_id cursor semantics with at-least-once delivery and re-issuability. Adds context not in 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 blocks until the next steer event and returns it. It uses specific verbs ('BLOCK', 'await', 'return') and distinguishes itself as read-only and owner-scoped. Sibling tools like me.session_event or me.sessions serve different functions, so purpose is well-defined.

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: REQUIRES team mode, owner-scoped, explains loop pattern (handoff -> await_steer -> ack -> execute -> handoff -> await_steer again). Includes when to use on timed_out and how to reuse cursor. Mentions alternative for listing sessions (me.sessions). Also specifies rejection codes.

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?

Beyond annotations, the description discloses rejection codes, event limit (500), blank summary refusal, team mode requirement, owner scope, and channel provenance. It also notes that steer/human posts are refused. 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?

Despite length, the description is well-structured with clear headings (PURPOSE, CHANNEL PROVENANCE, REQUIRES, WHEN TO CALL, WHEN NOT TO CALL, REJECTION CODES, Auth). Every sentence adds value, and the critical information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 required params, enums, output schema), the description covers all necessary aspects: usage context, rejection reasons, prerequisites, and authorization. Since an output schema exists, return values are not needed in description.

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 descriptions for all parameters. The description adds extra context: summary truncation, decision vs chat message, reservation of 'human' actor for cockpit, and clarification of 'ack' and 'steer' event types. This enriches schema definition.

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 appends a TYPED TEAM EVENT to a Governed Session's timeline, with specific event types and actor roles. It distinguishes from siblings like me.sessions (read back) and me.await_steer (receiving steers from cockpit), and explicitly contrasts the agent-side vocabulary from cockpit-originated events.

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 includes explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, detailing specific scenarios (handoffs, pushbacks, plan previews, gates, acks) and warnings against using as a chat log or for recording steers. It also mentions channel provenance and team mode requirements.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the behavioral context that search is currently limited to agentic principles only, which is valuable beyond what annotations provide. 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 concise, front-loads the purpose, and uses only necessary sentences. It is well-structured with clear sections for usage guidance and a note about limitations.

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, the description does not need to detail return values. It covers the tool's purpose, usage context, limitations, and fallback options completely, making it self-sufficient for an agent.

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 descriptions for both parameters. The description adds meaning by explaining the search scope (matches against title, definition, rationale, cluster) and providing example queries, which enhances understanding 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 searches Blueprint principles by free-text query and returns closest matches ranked by relevance. It provides concrete examples like 'reversibility' and distinguishes from the sibling tool principles.list, making the purpose specific and unambiguous.

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

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

The description explicitly advises when to use this tool over principles.list: 'Prefer this over principles.list when you have a specific topic in mind.' It also notes a current limitation (covers only 10 agentic principles) and offers fallback using principles.list with lens parameters for other principle sets.

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 are minimal (all false hints), so the description carries the full burden. It discloses that the tool is 'write-only, no auth required, single insert into UserFeedback' and specifies privacy behavior: 'contact_email is stored ONLY when permission_to_follow_up=true, and that fact is confirmed back in the response.' This goes well beyond the 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 clear sections (purpose, WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR). It is front-loaded with the core purpose and every sentence provides necessary guidance without 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 optional parameters, minimal annotations, and the presence of an output schema, the description covers purpose, usage, behavioral traits, privacy, and interaction flow. It is fully sufficient for an agent to decide when and how to invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing conversational prompts for each parameter (e.g., 'Ask the user: What was most helpful?'), which helps the agent know how to collect the data. This extra context justifies a score above baseline.

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

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

The description clearly states the tool 'records explicit free-text user feedback about the Blueprint, this tool surface, or a specific principle/example.' The verb 'records' and specific resource 'user feedback' make the purpose unambiguous, and it distinguishes itself from the sibling tool 'signals.report' by contrasting feedback vs. value-moment metrics.

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 provides 'WHEN TO CALL' (only when the user explicitly requests feedback) and 'WHEN NOT TO CALL' (proactively, silently, or to substitute for signals.report). It also specifies that contact_email should only be stored with explicit permission, offering clear boundaries.

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 description discloses key behaviors: long-running LLM call (60-180s), server-minted run_id, client timeout recovery via run_id, private_session disabling persistence, typed failures (same as architect.validate), and calibration disclosure that grades are directional. Annotations (readOnlyHint=false, destructiveHint=false) are consistent and the description adds extensive context beyond 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 lengthy but well-organized with bold section headers and a clear flow from purpose to usage to inputs. All sentences are informative, though some redundancy could be trimmed (e.g., repeated emphasis on not retrying). Overall, it earns its length.

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 (7 parameters, output schema, multiple sibling tools), the description covers all necessary aspects: return values (spec_classification, per-law findings, readiness score), alignment with sibling scorer, client timeout recovery, and privacy options. It is complete for effective use.

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 descriptions for all 7 parameters. The description adds valuable context beyond the schema, such as instructions for implementation_context (send full text, concatenation rules), explanation of repository grouping, session_id ownership check, and private_session effect. However, some parameter details are still left to 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 is a 'first-pass specification-quality review of a WRITTEN SPEC' against the '8 laws of the Spec Quality Blueprint'. It distinguishes itself from sibling tools architect.validate and design.validate by specifying the lens (written intent vs architecture vs surface). The verb 'validate' and resource 'spec' are specific, with explicit scope.

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' and 'WHEN NOT TO CALL' sections, clearly stating that it should be used for governance/quality reviews of specs and not for built code or rendered surfaces, which should go to sibling validators. It also explains client timeout handling and private session 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, idempotentHint, destructiveHint. The description adds significant context: read-only and idempotent behavior, aggregated sources (AIToolCallLog + ValueEvent + AIValidationRunLog), auth requirements (Bearer token, Pro/Teams plan), and the private_session effect (bypass logging). 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?

Well-structured with clear sections (Pro/Teams, WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR, Auth, Residency). Every sentence adds value; no fluff or repetition. Front-loaded with essential purpose.

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, the description need not detail return values. It briefly lists them and covers all other aspects (behavior, auth, residency, parameter usage). 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%, so baseline is 3. The description explains the private_session parameter (skip logging for this call) beyond what the schema states, adding value. It also mentions the default 30 days, which is already in schema, but the extra context justifies a 4.

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

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

The description clearly states the tool summarizes the caller's tool-usage patterns and value signals over a configurable window. It lists specific return fields (tool_call_counts, top principles, value_event_counts, readiness trend), distinguishing it from sibling tools like 'me.learning_path' or '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?

Explicit WHEN TO CALL and WHEN NOT TO CALL sections provide clear guidance. It states to call when user asks about 'how is the Blueprint helping' and warns against proactive use or comparing users, which effectively differentiates from alternatives.

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