AI Design Blueprint

Report Value Event

signals.report

Pro/Teams — records a value moment (e.g. review_confidence, runtime_risk_found, workflow_clarity) after a successful validate run on any lens — architect.validate, design.validate, or spec.validate — or a doctrine session. Each event captures event_type, surface_used (mcp/web/cli), perceived_value (1-5), and an optional brief_context — structured fields only, NO prompts or code stored. WHEN TO CALL: after architect.validate, design.validate, or spec.validate returns a clearly useful result AND the user has acknowledged the value (or you ask them "would you rate this 1-5?"). Each validator's response carries an explicit next_step instruction telling the agent to OFFER this call — surface that offer to the user. WHEN NOT TO CALL: silently or without the user's awareness; on every validate (only after a clear value moment); to capture intent or speculative value. If the user declines, do not retry within the same session. BEHAVIOR: write-only, single insert into ValueEvent. Auth: Bearer , Pro or Teams plan required. UK/EU residency. Do NOT include proprietary code, prompt content, or PII in brief_context — it surfaces in admin AI-visibility dashboards. Expect a 1-line acknowledgment in the response; the structured feedback is then aggregated server-side.

Input Schema

TableJSON Schema

Name	Required	Description
`team_size`	No	If the user mentions their team size during the session, record it here. Do not ask for it explicitly — only capture if volunteered.
`event_type`	Yes	Pick the type that best matches what just happened: 'review_confidence' — a validator lens (architect.validate / design.validate / spec.validate) returned aligned; 'runtime_risk_found' — a validate run found violations; 'workflow_clarity' — principles/examples clarified a design decision; 'agent_setup_success' — user successfully wired up an agent or MCP tool; 'onboarding_helped' — user understood how to start using the Blueprint; 'research_time_saved' — user found relevant doctrine faster than expected; 'team_alignment' — Blueprint helped align a team on agentic design; 'other' — use only if none of the above fit.
`surface_used`	No	Where the value was experienced. Use 'mcp' when called from Claude Code, Cursor, Windsurf, or any MCP client. Use 'principles' if the user was browsing or searching principles. Use 'examples' if the user was reading implementation examples. Use 'for-agents' if the user came via the /for-agents page. Use 'learn' or 'certification' for course-related sessions.
`brief_context`	No	1–2 plain-English sentences summarising what was helpful. Example: 'Validation identified a missing approval gate before email send.' No code snippets, no proprietary content, no user PII. Max 500 chars.
`workflow_stage`	No	Infer from what the user was doing: 'exploring' — reading doctrine, browsing principles; 'designing' — planning architecture or agent flows; 'implementing' — writing or refactoring code; 'reviewing' — running a validator lens on existing code, a surface, or a spec; 'shipping' — preparing for production or deployment.
`perceived_value`	No	Ask the user: 'On a scale of 1–5, how valuable was this session?' Map their answer directly: 1=low, 5=high. Do not guess — only set this if the user gave an explicit score.
`would_recommend`	No	Ask the user: 'Would you recommend the Blueprint to a colleague?' Set true/false based on their answer. Only set if asked — do not assume.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

TDQS

A4.9/5.0

Behavior5/5

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

The description goes far beyond the sparse annotations (all false). It discloses the write-only, single-insert behavior, auth requirements (Bearer token, Pro/Teams plan), UK/EU residency, the exclusion of code/PII from brief_context, and the exact response format (1-line acknowledgment). This fully informs the agent of side effects and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but tightly organized into labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and front-loaded with the core purpose. Every sentence conveys a distinct requirement or constraint; there is no filler or repetition. The structure improves scannability despite the length.

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

Completeness5/5

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

Given the tool's complexity (7 optional parameters, sensitive data restrictions, multiple call contexts) and the existence of an output schema, the description is complete. It covers auth, data handling, response behavior, and privacy rules, leaving no critical gap for an agent to misuse the tool.

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

Parameters4/5

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

The schema already provides 100% parameter descriptions, so the baseline is 3. The description adds extra semantics for key parameters, such as interpreting event_type examples, clarifying that perceived_value must be explicitly requested and not guessed, and mapping surface_used to contexts like 'mcp' for MCP clients. It does not cover every parameter, but the schema does, and the added value is meaningful.

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

Purpose5/5

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

The description clearly states the tool records a value moment after a successful validate run or doctrine session, with explicit examples of event types. It distinguishes itself from sibling tools like signals.feedback by specifying the exact triggering conditions (after architect.validate, design.validate, spec.validate) and the optional nature of the capture.

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

Usage Guidelines5/5

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 requirement to offer the call after a validator's next_step instruction, not to call silently, not to call on every validate, and not to retry if declined. This leaves no ambiguity about appropriate usage.

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

All AI Design Blueprint tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose within its domain: the validators are differentiated by lens (architect/design/spec), content tools are split by entity (principles/clusters/guides/examples/assets) with list/get/search variants, and even the me.* and handoffs.* tools have non-overlapping functions. The only near-overlap (architect.validate vs architect.validate_consensus) is explicitly disambiguated by the consensus variant's description.

Naming Consistency4/5

Tool names consistently use a domain prefix (architect., principles., me., etc.) and snake_case throughout. While most are action-oriented (validate, list, get, search, add, await, report, summarize), some me.* and handoffs.* names are noun phrases (me.learning_path, handoffs.agency) that don't signal the action as clearly, creating minor deviation from a pure verb_noun or action pattern.

Tool Count3/5

At 29 tools, the set is heavy but justified by the server's broad multi-domain scope (doctrine, validation, learning, support, and team analytics). Each tool has a distinct role, but the number exceeds the typical well-scoped range, and some content types (e.g., examples) could have been consolidated without losing function.

Completeness4/5

The server covers its apparent domains thoroughly: doctrine content has list/get/search for most entity types, validation covers architecture/design/spec with consensus and certification, and user learning/support have appropriate tools. Minor gaps exist—e.g., examples have no list-all endpoint, and session management is web-only—but none are blocking for core workflows.

Resources

Need Help?