AI Design Blueprint Doctrine

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

Annotations (readOnlyHint=false, idempotentHint=false) are consistent, and the description adds extensive context beyond them: 60-180s LLM latency exceeding client idle budgets, t=0 progress event carrying run_id, no-retry-on-timeout guidance, the 3-attempt retry budget, atomic/no-cancel/no-resume contract, auth/plan requirements, UK data residency, OpenAI transfer under SCCs, and the exact outcomes enum. This is unusually rich behavioral disclosure.

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

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

The critical operational rule (DO NOT RETRY on timeout) is front-loaded, which is good, but the body is massively over-long and repeats the same ideas several times: the retry budget, the recovery path, the fingerprint/void-the-run doctrine, and payload completeness each appear multiple times. The content is relevant, but the sizing is bloated for a 2-parameter tool.

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 high-complexity, high-stakes mutation tool with an output schema present, the description covers eligibility, failure modes, recovery, data-handling, and outcomes far beyond the minimum. Nothing an agent needs to invoke or recover from cert is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning about the `code` parameter: it must be verbatim identical to the validated code (SHA-256 fingerprint comparison), may be omitted only while the 24h cert-retry hold persists, and mismatches reject with code_fingerprint_mismatch. That semantic detail exceeds the schema text.

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

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

States a specific verb (certify) and resource (a production_ready architect.validate run), and immediately distinguishes itself from the sibling architect.validate by describing the second-pass adversarial review. An agent can tell exactly what this tool produces (a certified badge or a downgrade) without opening the schema.

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 (only after validate returned tier=production_ready, user wants the badge, code untouched), explicit NOT-for cases (draft/emerging/not_applicable), and an explicit alternative/recovery (`me.validation_history(run_id=...)`). The eligibility gate and typed rejection enum further pin down exactly when it applies.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds far more: 60-180s LLM latency with server-side 6-min budget, run_id minted at t=0 in the first progress event, 30s keepalive, atomic persistence of four records with URL stripping on rollback, plan/auth gating, UK data residency with US OpenAI processing, and a disclosed ~20-67pt score-variance band. This is unusually rich behavioral context, not a restatement of 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?

It is structured with caps headers and is front-loaded with the timeout warning, which is the highest-value content. However at roughly 1,500 words it is heavily redundant: run_id recovery is stated twice, payload-completeness guidance appears in three separate sections (PAYLOAD COMPLETENESS, TWO COMPLETENESS AXES, and the NEXT STEP back-reference), and score-variance is restated in both the description and the repository schema field. The size is defensible given the timeout/cost stakes, but the repetition is not.

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?

An output schema exists so return values need not be explained, yet the description still summarizes code_classification, per-principle findings, readiness tiering, the reproducibility envelope, and persistence_status, plus the private-by-default 404 caveat on badge/review URLs. For a long-running, authenticated, iterative, recovery-sensitive tool, nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: repository is an iteration key where any suffix silently severs the prior_run_baseline chain, focus_area fails explicitly rather than widening on an unmatched value, and private_session also disables run_id recovery and prior-run anchoring. The implementation_context DO/DON'T guidance (no `...` placeholders, split by file rather than truncate, stub imported module surfaces) meaningfully extends the schema text.

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

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

The opening sentence names a specific verb (first-pass doctrine review) and resource (agentic code/workflow) scoped against a named doctrine (10-principle AI Design Blueprint). It explicitly distinguishes itself from siblings: cert = adversarial second pass on payload completeness, validate_consensus = N=3-5 aggregated median, me.validation_history = recovery handle. An agent can route between these without opening any other schema.

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 wants a governance audit, readiness score, or production_ready badge') and WHEN NOT TO CALL ('non-agentic plumbing ... returns tier=not_applicable ... submit the OWNING agentic workflow instead'). It also names the preferred alternative for the stability case ('for decisions where stability matters more than speed, call architect.validate_consensus'), which is textbook when/when-not/alternative 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?

The description goes far beyond the annotations. It discloses the long-running nature (~80-120s), the N parallel LLM calls, the cost multiplier (N × LLM bill), the private_session=True behavior for children, the persistence contract (children do not persist, the consolidated row does), the auth gate, and the typed failure modes including consensus_quorum_failed. It even warns about MCP client timeout behavior and provides a recovery path. This is exemplary behavioral disclosure.

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

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

The description is long but every section earns its place: timeout warning, recovery, when-to-call, when-not-to-call, behavior, auth, inputs, outputs, typed failures. It is front-loaded with the most critical operational warning (DO NOT RETRY ON TIMEOUT) and structured with clear section labels. It could be slightly tighter, but the density of actionable information justifies the 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?

For a complex tool with 9 parameters, an output schema, and significant operational risk, the description is complete. It explains the output fields (score_consensus_median, score_stdev, score_range, mode_stability_min_pct, per_principle, representative_response), the failure modes, the auth requirements, the persistence semantics, and the relationship to the sibling architect.validate. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the semantics of key parameters: n (range 2..5, default 3, cost implication), repository (iteration key, persisted as prior baseline), and implementation_context (send full file contents verbatim, truncation causes hallucinated findings). It also clarifies that private_session is implicit for children. The only minor gap is that it doesn't enumerate every parameter, but the schema already covers them.

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

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

The description opens with a specific verb and resource: 'N-shot CONSENSUS doctrine review of agentic code.' It clearly distinguishes consensus mode from the single-shot architect.validate by explaining the anchoring difference (60/C anchored vs 98/A unanchored). The tool's purpose is unmistakable and differentiated 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?

The description provides explicit WHEN TO CALL and WHEN NOT TO CALL sections. It names the alternative (architect.validate) and the exact condition that selects it: use consensus when the user wants an honest unanchored first-pass score; use single-shot validate when iteration delta against a prior run is needed. It also gives recovery guidance on timeout, which is a usage condition.

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 carry readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable context beyond annotations: 'no auth required' and 'Asset artefacts are regenerated on every deploy from the canonical doctrine.' These behavior disclosures help the agent understand side effects and access 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 detailed and front-loaded with the core purpose, then expands logically into output format, when-to-call, and behavior. It is slightly dense with the full enumeration of formats and platforms, but each clause carries useful information, so no sentence is wasted.

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 zero-parameter, read-only tool with an output schema and full annotations, the description covers purpose, output shape, usage boundaries, and behavioral traits comprehensively. An agent has everything it needs to decide whether and how to call this tool correctly.

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

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

The input schema has zero parameters, so there is nothing for the description to add. Per the baseline for 0 parameters, the score is 4; the description appropriately focuses on output and usage rather than parameter details.

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-resource pair ('list downloadable doctrine and agent asset artifacts') and clearly states the tool's purpose: to import the Blueprint as native skill/rule files into AI coding tools. It also distinguishes itself from siblings by explicitly routing doctrine content to principles.list/get and guides.list/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?

Explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections give precise criteria for use, including when to avoid it (for live MCP tools) and what alternatives to prefer (principles/guides). This leaves no ambiguity about selection.

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 safety profile is covered. The description adds valuable behavior beyond the annotations: the 404-shaped error_payload on unknown slug, the requirement for exact slug matching with no normalization, and cacheability per slug. 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 organized with clear sections: returns, when to call, when not to call, and caveats. Each sentence serves a distinct purpose, and the most actionable facts (return contents and routing) come first. No filler or 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 a single parameter, a rich output schema, and annotations covering idempotency/read-only behavior, the description is complete. It covers selection criteria, exact-match requirements, error behavior, and the relationship to sibling tools, leaving no gap an agent would need to resolve elsewhere.

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

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

Schema coverage is 100%, and the schema already describes the slug with examples, so the baseline is 3. The description adds meaningful parameter semantics by warning that the slug must exactly match the value emitted by clusters.list and that no normalization is applied, which is not in 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?

Description starts with a specific verb and resource: 'Get one principle cluster by stable slug.' It enumerates exactly what is returned (cluster definition, shared rationale, member principles) and distinguishes itself from clusters.list and principles.get by naming them explicitly.

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 WHEN TO CALL section gives concrete triggers including example slugs and the prior-list-response case. The WHEN NOT TO CALL section names three alternatives with exact routing conditions: principles.search for natural language, clusters.list for discovery, and principles.get for a single principle. This is exemplary 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 disclose readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful content expectations (stable slugs, linked principle titles) but no additional behavioral traits like pagination, rate limits, or auth needs. It does not contradict annotations, but the added behavioral context is minimal.

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 short sentences, front-loaded with the primary action. The second sentence adds necessary guidance on when to use alternatives. No redundant information or wasted words.

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

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

Given the tool's simplicity (no parameters), the presence of an output schema, and strong annotations, the description fully covers the use case, including context for when to use this list tool versus related tools. It is complete and self-sufficient.

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

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

The tool has zero parameters, and the schema's property map is empty. Per the baseline for 0 params, a score of 4 is appropriate — the description isn't required to explain parameters, and it doesn't attempt to, which is correct.

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 'List all principle clusters with their stable slugs and linked principle titles' — a specific verb and resource. It distinguishes from siblings by naming clusters.get and principles.list as alternatives, making the purpose unmistakable.

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: 'Use this to discover which clusters exist before drilling in with clusters.get or filtering principles.list by cluster.' Also states a clear exclusion: 'Prefer clusters.get when you already know the cluster slug and need full detail.' This meets the highest standard for usage guidance.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses error behavior ('Returns error_payload on unknown slug') and explains the two possible entry kinds, including the conditional additional fields for pattern entries. This adds significant context not captured in annotations.

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

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

The description is front-loaded with the core action and return types, then uses conditional clauses to explain variants. Despite length, every sentence contributes necessary information; no fluff or repetition.

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

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

For a tool with one parameter and an output schema, the description thoroughly explains return values, error handling, and edge-case entry variants. It also positions the tool within the broader toolset, making it complete for an agent deciding whether to invoke it.

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

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

The only parameter, 'slug', is fully described in the input schema (100% coverage). The tool description does not add new semantic details beyond using the term 'stable slug', which already appears in the schema. Baseline 3 is appropriate since schema handles the parameter meaning.

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

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

Purpose is explicitly stated: 'Get one curated example by stable slug.' It names the verb and resource, and distinguishes from siblings by contrasting with examples.search and guides.get (e.g., 'prefer examples.search when filtering ... prefer guides.get when the caller wants a full walkthrough').

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-use guidance: 'Use this when you already have the slug from examples.search, a principles.get response, or a guide cross-link', and names alternatives with conditions: 'prefer examples.search when filtering by topic / principle / difficulty / library; prefer guides.get when the caller wants a full walkthrough'.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the base safety profile is covered. The description adds valuable non-obvious behavioral context: relevance ranking, server-side limit capping, inclusion of first-party patterns with doctrine binding, and a nuanced pattern-preference rule that never outranks a genuine failing-principle match. This goes well beyond the structured annotations, though it does not describe error handling or pagination beyond the limit.

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

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

The description is longer than average but every sentence adds substance: purpose, filter summary, return fields, routing guidance, pattern caveats. It is front-loaded with the core action and becomes more detailed as it goes. No filler, though slightly dense; a 4 reflects the efficient but information-rich 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's moderate complexity (6 params, output schema present, sibling routing needed), the description covers all essential angles: what it returns, when to use it, when not to use it, behavioral nuances of result ranking and pattern inclusion, and links to examples.get for hydration. The output schema handles return-field details, so the description need not repeat them. Nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter mentions ('principle_ids', 'difficulty', 'library') largely restate the schema, but it adds one non-schema nuance: pattern_family 'implies patterns only' and the pattern preference behavior tied to it. This is a small increment over the schema, so 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Search curated examples by free-text query, ranked by relevance', then enumerates the optional filters and the returned fields (slug, title, summary, etc.). It also explicitly differentiates itself from siblings (examples.get, guides.search, principles.search) by naming what each is for, so an agent can distinguish them without opening schemas.

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

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

Provides explicit when-to-use guidance: 'Use this when the user describes a use case, technique, or library and wants matching examples', and follows with clear alternatives for related siblings ('prefer examples.get when you already have the slug', 'prefer guides.search...', 'prefer principles.search...'). This is direct, actionable routing with no inference required.

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, and non-destructive behavior. The description adds useful context about the return structure (sections, action items, linked principles) and the stability of the slug, going beyond what annotations 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?

Three sentences, front-loaded with the core action, then return contents, then usage guidance. 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?

For a simple one-parameter tool with full annotations and output schema, the description covers the purpose, return contents, and usage alternatives comprehensively. No gaps identified.

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 slug parameter, which already includes examples. The description repeats the examples and adds that the slug comes from guides.list or guides.search, but this is marginal 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 gets a full application guide by stable slug, with examples. It distinguishes itself from siblings by focusing on slug-based retrieval and listing return contents.

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

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, so the safety profile is covered. The description adds the discovery context but does not disclose additional behavioral traits such as pagination or output size. With annotations present, this is adequate but not rich.

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 adding value: what it does, when to use it, and how to choose alternatives. No redundancy, front-loaded with the 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?

For a simple list tool with no parameters, an output schema, and strong annotations, the description fully covers its role, usage context, and sibling differentiations. Nothing is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description needs no parameter explanation and adds no confusion. The schema is trivially complete.

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 and resource ('List application guides') and clarifies the scope ('show how Blueprint principles apply to engineering challenges'). It also distinguishes from siblings by framing this tool as the discovery entry point before drilling in.

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 names when to use this tool versus alternatives: 'Use this to discover which guides exist before drilling in. Prefer guides.search when the user describes a topic or failure mode in natural language. Prefer guides.get when you already know the guide slug and need full detail.' This gives clear, actionable 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, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context by specifying that the search matches against 'section answers and action items', which goes beyond the schema and clarifies the search's scope and semantics. It does not mention pagination or result ordering, but the output schema likely covers return format, and the bar is lower given annotation coverage.

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

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

The description is three sentences, each earning its place: first defines the action, second gives the use case, third provides sibling alternatives. No redundant or vague wording. It is front-loaded with the primary purpose and is highly scannable.

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 simple search tool with comprehensive annotations, full schema coverage, and an output schema present, the description covers all necessary context: purpose, use case, and alternatives. It doesn't need to explain return values because the output schema exists. The description is complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both 'query' and 'limit'. The description reinforces that query is free-text and matched against content, but it doesn't add significant new meaning beyond the schema. Baseline of 3 is appropriate when the schema carries the parameter documentation.

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

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

The description clearly states the tool's function: 'Search application guides by free-text query' with specific scope ('matched against section answers and action items'). It also distinguishes from siblings by explicitly naming alternatives (guides.get, guides.list), providing clear differentiation.

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

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

The description gives explicit guidance on when to use this tool ('Use this when the user describes an engineering challenge... and wants matching guides') and when to prefer alternatives ('Prefer guides.get when you already have the guide slug; prefer guides.list when you need the full inventory'). This satisfies both when-to-use and when-not-to-use criteria.

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

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

Annotations declare the mutation profile (readOnlyHint false, idempotentHint false, openWorldHint true), but the description adds substantial context beyond them: write-only single insert, Bearer token required on any plan, data at rest in the UK, the response returning a ticket id + scope, and the warning that this creates a sales-visible record requiring user confirmation.

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 what it does, then clearly labelled WHEN TO CALL / WHEN NOT TO CALL / BEHAVIOR sections. Slightly verbose, with the scope definitions and the response-confirmation detail bordering on redundant against the schema and output schema, but every section is scannable and purposeful.

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 side-effecting write tool with an output schema, the description covers everything an agent needs: purpose, the confirmation prerequisite before firing, auth requirements, routing alternatives, and the persistence/visibility implications. Return values are already described by the output 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%, so the schema already documents all 10 parameters. The description still adds real value by defining the four engagement scopes (workflow sprint, proof-of-concept, pilot support, advisory) that map onto the reason and support_type fields.

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

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

States a specific verb and resource ('submit an agency engagement enquiry ... for a founder-led discovery call') plus the persistence side effect ('Persists an AgencyHandoff row routed to the agency inbox'). It explicitly distinguishes itself from sibling handoff tools by naming partnership and operator routing.

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

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

Gives explicit WHEN TO CALL (paid hands-on expert engagement need beyond self-service, user explicitly asks to talk to team/book a discovery call) and WHEN NOT TO CALL, routing free training/partnerships to handoffs.partnership and support/billing/access to handoffs.operator, plus a proactive-sales exclusion.

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

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

Beyond the annotations, the description discloses that this is a write-only, single-insert, side-effecting operation that creates a human-visible ticket, requires Bearer auth, stores data at rest in the UK, and returns a confirmation with ticket id and topic. This significantly enriches the annotation signals and sets correct expectations for a handoff action.

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?

Although longer than average, the description is well-structured with explicit headers (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and front-loads the core purpose and side-effect warning. Every sentence carries relevant routing, confirmation, or behavioral information with no filler.

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

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

For a side-effecting, human-visible ticket creation tool, the description covers the essential operational context: when to invoke, when not to, user confirmation requirement, auth, data residency, and response shape. Since the output schema exists and parameters are fully documented, nothing critical is missing for an agent to invoke this safely.

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 the baseline is 3 and the description does not need to heavily compensate. The description enumerates several persisted fields (reason, topic, page_url, agent_name, agent_platform, trace_summary) but adds little semantic detail beyond what the schema already provides. It also mentions user_email, which is not actually a parameter in the schema, creating a minor mismatch.

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

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

The description opens with a specific verb and resource: it 'creates a support handoff record' when human review or operator follow-up is needed. It clearly names the scope (support handoffs) and distinguishes itself from siblings by saying partnership/agency enquiries use handoffs.partnership / handoffs.agency and content questions use principles.search / guides.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?

The description provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, including concrete trigger conditions ('user explicitly asks for human help, hits a billing/access issue, or the agent has tried the doctrine tools'). It also names alternative tools to use instead, so the agent has clear routing guidance.

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

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

Annotations already signal a non-read-only write, but the description adds meaningful behavioral context: write-only, single-insert, side-effecting, creates a human-visible ticket, auth requirements, UK data at rest, and response content. This goes well beyond the structured annotations without contradicting 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 organized into clear labeled sections with all critical information front-loaded. Every sentence earns its place, covering usage, exclusions, behavior, auth, and response expectations without repetition.

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

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

For a 9-parameter write tool with an output schema, the description provides all necessary invocation context: when to call, when not to call, confirmation requirement, side effects, auth, and response contents. The output schema covers return-value details, so nothing important is missing.

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

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

Schema coverage is 100%, so the input schema already describes every parameter. The description mentions that a PartnershipHandoff row is routed and the user is contacted, but adds little parameter-specific meaning beyond the schema; the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'creates a partnerships handoff record' for design-partner, ecosystem, training, or advisory conversations. It differentiates from sibling tools by naming the partnerships inbox and the recipient team, making the tool's scope unmistakable.

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 identify exact triggers, require explicit user confirmation, and name alternatives: handoffs.operator for support/billing/access and handoffs.agency for paid engagements. This leaves no ambiguity about routing.

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

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

Beyond the annotations, it discloses auth requirements (Bearer token, any plan), data residency (UK), write-only single-insert behavior, visibility scope (owning user only), and downstream surfacing on me.learning_path and me.coaching_context. Annotations already establish a non-read-only, non-idempotent write, and the description adds substantial operational context.

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

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

The text is front-loaded and organized into clear sections: purpose, note definition, persistence, WHEN TO CALL, WHEN NOT TO CALL, and BEHAVIOR. Despite its length, every sentence adds actionable guidance or behavioral context.

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

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

With full schema coverage, annotations, and an output schema, the description supplies everything else an agent needs: auth, data location, visibility, usage boundaries, response confirmation, and related tools. No material gaps remain.

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 the input schema already documents all three parameters. The description adds useful semantic context about what qualifies as a note, how it maps to Blueprint principles, and how it is persisted, though it also mentions stage_slug while the schema uses stage_id.

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

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

The description states a specific verb and resource: append a free-text evidence note to a specific stage in the caller's active course. It clearly distinguishes this from logging conversation turns or recording intent, and names me.coaching_context as a related tool.

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

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

It provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, including the condition that the user has articulated something concrete, not intent or speculation. It also names me.coaching_context as a pairing tool to close evidence gaps.

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?

Even with annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds substantial behavioral detail: blocking long-poll, at-least-once durable cursor delivery, best-effort in-process wake-up, timed_out only after a confirming read, and explicit 'never writes events'. This is consistent with and extends 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 long and uses heavy formatting (caps, sections), but it is structured into deliverable pieces: purpose, delivery guarantee, loop, requirements, rejection codes, auth. Nearly every sentence carries unique information, and the key action is front-loaded in the first sentence, though it could be tightened.

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 interaction complexity, the description covers all operational aspects: blocking semantics, delivery guarantee, loop sequence, team-mode requirement, owner scoping, rejection codes, auth plan, and read-only nature. An output schema exists to cover return values, so nothing essential is missing.

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

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

Schema description coverage is 100% and the parameter descriptions are already rich (timeout clamping, cursor semantics, ownership). The description adds value beyond the schema by specifying the loop usage—re-calling with the returned after_event_id on timed_out—and by pointing to the parameter descriptions for the authoritative semantics, so an agent has a complete picture.

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 opens with a specific verb and resource: 'BLOCK until the session owner posts the next steer event to a Governed Session from AIDB Studio, then return it.' It clearly differentiates from siblings like me.session_event (posting events) and me.sessions (listing sessions) by defining its exact role as the waiting/reading counterpart in the handoff loop.

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

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

Provides an explicit 'THE LOOP' section that tells exactly when to call the tool: after posting a handoff via me.session_event, on every received steer, and again after timed_out with the returned cursor. It also states requirements (team mode, owner scope) and lists rejection codes, so an agent knows both when and when not to use it.

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 description doesn't need to repeat those. It adds valuable context beyond annotations: it notes the tool is 'read-only, idempotent' (matching annotations), details auth requirements (Bearer <token> any plan), explains that state changes only when evidence is added, and describes the output structure. This is slightly above the baseline 3 because it provides operational context like rate-of-change and output details.

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: a behavior summary, explicit WHEN TO CALL / WHEN NOT TO CALL, and a BEHAVIOR section. It's information-dense but each sentence adds value—no fluff or repetition. The description front-loads the core purpose and then provides usage boundaries, making it scannable for an agent.

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 0 parametersasi and an output schema that likely describes the structure, the description is complete. It covers purpose, usage, when-not-to-call, auth, and the required output fields (thin_stages, missing principles, evidence_count, coaching_note). It also links to related tools. No critical gaps remain for an agent to call it correctly.

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

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

The tool has 0 parameters, and schema description coverage is 100% (trivially, since no properties). The description appropriately states 'Authenticated' and mentions the auth token, which is the only input consideration. With no parameters to describe, the baseline is 4, and the description doesn't need to add parameter semantics but does clarify auth context.

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 stages in the caller's active course with thin recorded evidence, including missing principle slugs and diagnostics. This is specific with a verb ('returns') and resource ('stages in the caller's active course'), and it distinguishes itself from siblings like me.learning_path or me.validation_history by focusing on evidence gaps.

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 call: when the user asks 'what should I work on next' or 'what's weak in my Blueprint progress'; and when not to call: to lecture on already satisfied principles or on every conversation turn. It also mentions pairing with me.add_evidence to close gaps, providing clear routing among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces these while adding valuable context beyond annotations: auth requirement ('Bearer <token>'), plan availability ('any plan, including basic'), and the state-change semantics ('state changes only when the user completes a stage'). This fully discloses the operational behavior an agent needs.

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

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

The description is front-loaded with the core purpose, then organized into clear WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR, and Auth sections. Every sentence adds operational value, and the structure makes it easy for an agent to scan and extract the relevant decision criteria.

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 zero-parameter, read-only tool with an output schema, the description is fully complete: it covers auth, scope, return fields, eligibility semantics, usage timing, and exclusions. There are no missing details an agent would need to invoke this tool correctly.

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

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

The input schema has zero parameters, so there is no parameter semantics to document. The description correctly focuses on the returned state rather than inputs, and the 100% schema description coverage means nothing is left undocumented. Baseline 4 is appropriate for a zero-parameter tool.

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

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

The description opens with a specific verb and resource: 'returns the caller's Blueprint learning-path state' and enumerates the exact data returned (current course slug, stage progress, certification status, Capstone eligibility, next recommended stage). It also clearly scopes the tool to the caller's own path, distinguishing it from any tool that might read another user's progress.

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 triggers ('where am I', 'what's next', 'am I Capstone-eligible') and equally explicit WHEN NOT TO CALL exclusions (not a heartbeat, not for reading another user's progress). This gives an agent unambiguous decision rules with no need to infer usage.

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

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

Annotations only mark mutating, non-idempotent, non-destructive behavior; the description adds substantial constraints: channel provenance refusing steer/human, team-mode requirement, owner-scoping, 500-event limit, blank-summary refusal, and durable channel stamping. It also states auth plan requirements. No contradiction with annotations.

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

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

The description is long but densely structured with labeled sections (CHANNEL PROVENANCE, REQUIRES, WHEN TO CALL, WHEN NOT TO CALL, REJECTION CODES, Auth), and the core purpose is front-loaded. A few phrases are redundant with the schema, but overall the length is justified by the number of constraints.

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—team-mode gating, channel provenance, error codes, auth, and call-ordering—the description covers prerequisites, exclusions, failure modes, and alternatives. Output schema exists, so return-value documentation is not needed. Nothing essential is missing.

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

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

Schema already covers 100% of parameters, but the description enriches them: ack semantics ('STARTED working on a steer'), summary truncation to 500 chars and content guidance, session_id ownership/team-mode requirement, and the explicit event_type/actor enumerations. This goes well beyond the 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 opens with a specific verb and resource: 'append a TYPED TEAM EVENT to a Governed Session's timeline (GEP-M6).' It enumerates the event vocabulary and explicitly contrasts with sibling flows by stating that steer events and human actors are refused, so an agent can tell it apart from me.await_steer and me.sessions.

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

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

WHEN TO CALL lists concrete triggers (role handoffs, pushbacks, plan previews, hard gates) and WHEN NOT TO CALL excludes chat logging and steer recording. It names the alternatives (me.await_steer, me.sessions) and gives an ordering rule: post ack first, then execute, then handoff.

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, and the description adds substantial context beyond those: owner-scoping, plan/auth requirements, newest-first ordering, 'light rows' for the timeline, team-only events, and the fact that sessions are created in the web app. 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?

Although the description is long, it is densely informative and each clause earns its place. The two-mode structure is front-loaded琳琅 and the read-only/auth note is quick, so an agent can parse the essential behavior without wading through 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?

For a tool with two modes, a team-event condition, plan restrictions, and relationships to several sibling tools, the description covers everything needed to select and invoke it correctly. The output schema exists to cover return values, so no explanation of those is missing.

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

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

The schema already describes session_id fully, including the 'Session not found.' behavior for non-owned ids, so the baseline is 3. The description adds value by explaining what session_id actually yields (run timeline light rows, team events) and how to get full results via me.validation_history, pushing it slightly 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 opens with a specific verb+resource pair: 'list or inspect the authenticated user's Governed Sessions'. It distinguishes two modes (no args lists all; session_id inspects one) and states the session's key characteristics, making it unmistakably different from sibling listing/inspection tools.

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

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

It explicitly explains when to use each mode, names the complementary tool for fetching full run results (me.validation_history), and tells the user how to attach new runs via architect.validate, design.validate, and spec.validate. This is clear routing guidance, not just a description.

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, and the description adds valuable behavioral context: that runs persist server-side, that run_id is surfaced in the first progress notification, that results are returned verbatim, and the auth/plan requirements. No contradiction with annotations; the description enriches beyond the structured fields.

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

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

The description is long, but every sentence earns its place given the three modes and multiple nuances (recovery, regression diff, sorting). It front-loads the core purpose and uses clear mode labels. Slightly dense, but not redundant; a 4 is fair because the length could be trimmed without losing meaning.

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 three lookup modes, their outputs, the auth requirement, and the strategic use case for avoiding unnecessary re-validation. With an output schema present and no nested objects, nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100% per the signals, but the description goes beyond the schema by explaining the purpose of each parameter, the mutual exclusivity and precedence rule, and the recovery semantics of run_id. It also clarifies that limit is ignored when run_id is provided and caps at 50, adding actionable detail not present in 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 authenticated user's validation run history across three lenses, including scores, grades, and tiers. It explicitly names the validate tools (architect.validate, design.validate, spec.validate) and maps each lens to its validator value, distinguishing this history tool from the validation tools themselves.

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

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

The description gives explicit guidance on when to use each of the three lookup modes, including a concrete recovery scenario for run_id (client timeout) and a clear directive to use modes 2 or 3 BEFORE re-validating to focus on regressions. It also notes mutual exclusivity and precedence (run_id wins).

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 and idempotentHint, so the safe-read nature is known. The description adds valuable behavioral context by enumerating the return fields (id, title, cluster, definition, rationale, implications, risk-if-violated), noting that laws also carry eponym and validator_questions, and specifying that unknown slugs return an error_payload. This goes beyond the annotation baseline and informs edge-case handling.

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 compact and front-loaded with the core purpose, then packs lens semantics, return fields, usage alternatives, and error behavior into three sentences. Every sentence contributes unique value without redundancy, achieving high informational density.

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 simple get-by-slug tool with two parameters, the description covers all necessary context: what the tool returns, how the lens parameter alters selection, when to use it versus alternatives, and how errors are handled. The presence of an output schema further reduces ambiguity, and the description still goes beyond by detailing the content of the response.

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

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

Schema coverage is 100% with descriptive parameter entries, so baseline is 3. The description enriches this by explaining the semantic meaning of each lens value ('architecture' = 10 agentic principles, 'surface' = 8 design laws, 'spec' = 8 spec laws) and by advising users to obtain slugs from principles.list, which is not explicit in the schema. This compensates well for the schema's bare listing.

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

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

The description opens with 'Get one doctrine entry by stable slug', clearly stating the verb and resource. It further distinguishes the lens values by naming exactly what each selects (10 agentic principles, 8 experience-design laws, 8 spec-quality laws), and explicitly contrasts with principles.list and principles.search, making it easy to identify the tool's unique role.

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

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

The description gives explicit usage instructions: 'Use this when you already have the exact slug from principles.list', and names alternatives: 'prefer principles.search when the user describes a topic or failure mode in natural language; prefer principles.list when you need every entry or every entry within a cluster.' This is textbook when/when-not guidance with specific alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context about lens selection (three doctrines), default behavior (architecture), and the ability to filter by cluster, going beyond structured fields. It doesn't contradict 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?

Four sentences, no filler. Front-loaded with the core purpose, then concise details on lens and guidance on alternatives. 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?

For a simple list tool with rich annotations, output schema, and sibling alternatives, the description fully covers purpose, usage, parameter semantics, and alternatives. No significant 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%, so baseline is 3. The description enriches both parameters: explains the lens enum values and maps them to validator rubrics (architect.validate, design.validate, spec.validate), and provides example cluster slugs, thereby adding meaning 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 'List Blueprint doctrine with stable slugs, titles, and clusters' with a specific verb and resource. It distinguishes itself from siblings by explicitly naming principles.search and principles.get and describing when each should be used 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?

Provides explicit usage guidance: 'Use this when you need the full inventory or want every entry in one cluster' and explicitly recommends alternatives: 'Prefer principles.search when...' and 'Prefer principles.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, so the description doesn't need to restate safety. It adds useful behavioral context: the results are 'ranked by relevance', it returns specific fields (title, cluster, definition, rationale, implementation heuristics), and for the 'all' lens each result 'names its lens'. This goes beyond annotations without contradicting 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 a single paragraph that front-loads the core purpose, then adds usage guidance, return details, and lens semantics. It's slightly long but every sentence adds information an agent needs. No fluff or repetition of schema details. The structure is logical and scannable.

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 moderate complexity, the presence of a full input schema, output schema, and annotations, the description is complete. It covers what the tool does, when to use it, how the lens works, what the results include, and the eponym matching behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by clarifying the lens semantics (e.g., 'architecture' = the 10 agentic principles, default) and by noting that queries also match on eponyms ('Hick', 'Fitts'). This enriches the meaning of the query parameter beyond the schema's generic 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 states a specific verb ('Search'), a specific resource ('Blueprint principles'), and the action ('by free-text query and return the closest matches ranked by relevance'). It explicitly distinguishes itself from the sibling 'principles.list' by stating when to prefer it, making it easy for an agent to tell them apart without opening schemas.

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

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

The description gives explicit guidance: 'Prefer this over principles.list when you have a specific topic in mind rather than wanting all principles.' It also explains how the 'lens' parameter selects the doctrine, provides example queries, and notes that laws match on eponyms. This is clear, actionable usage context with 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?

Adds substantial context beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false): write-only/no-auth, UK data residency, contact_email stored only when permission_to_follow_up=true, opening of a support inbox item, free text sent to OpenAI for triage, weekly pseudonymised lead-intelligence extract to OpenAI (US), and explicit rejection codes. This is far beyond what structured fields convey.

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 the purpose, then structured under WHEN TO CALL / WHEN NOT TO CALL / BEHAVIOR / REJECTION CODES headers. Dense but mostly earns its length given the privacy and data-flow complexity; a few clauses could be tightened.

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 9-parameter, privacy-sensitive, all-optional mutation tool with an output schema, this is comprehensive: it covers storage, follow-up permission, downstream data flows, private_session applicability, and validation rejection criteria. Because an output schema exists, return-value detail is appropriately not required.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add some meaning (the contact_email/permission_to_follow_up gating and the validity rule that a rating, what_helped/what_missing, or would_use_again answer is required). However, it also references non-existent 'category' and 'body' fields, so it does not clearly rise above the schema-documented 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?

States a specific verb+resource ('records explicit free-text user feedback about the Blueprint, this tool surface, or a specific principle/example') and explicitly distinguishes itself from signals.report. Minor deduction: it claims to capture 'category (bug, doctrine_critique, ...)' and a 'free-text body', neither of which exists in the schema, which slightly muddies what the tool actually records.

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 with trigger examples ('can you log this as feedback'), an explicit WHEN NOT TO CALL ('proactively, silently, or to substitute for signals.report'), and names the sibling alternative with the condition that selects it. Nothing is left to inference.

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

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

Annotations only carry readOnlyHint=false and destructiveHint=false, which is minimal. The description compensates heavily: 'write-only, single insert into ValueEvent', auth requirements ('sign-in required, with an active Pro, Pro Plus, Teams, Enterprise, beta, or trial plan'), 'Data at rest in the UK', and the critical warning that brief_context 'is stored as written, surfaces in admin AI-visibility dashboards, and may appear... in our weekly lead-intelligence extract to OpenAI (US)'. It also discloses the response shape: 'Expect a 1-line acknowledgment'. No contradiction with annotations.

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

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

The description is longer than typical but well-structured with clear sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) that make scanning easy. Almost every sentence earns its place, especially the auth, privacy, and PII prohibitions. It could be tightened slightly—some schema details are repeated—but the density is justified for a tool with this many safety constraints.

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, auth gating, privacy implications, and written-feedback storage—the description covers everything an agent needs: exact triggers, exclusions, auth plans, data handling, and the response expectation ('aggregated server-side'). The detailed schema and output schema handle the remaining parameter/return details, so nothing is left ambiguous 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 description coverage is 100% and each parameter already has a rich description in the schema (e.g., perceived_value's 'Do not guess: only set this if the user gave an explicit score'). The description mostly restates schema content ('perceived_value (1-5)', 'brief_context (up to 500 characters)') and omits some params entirely (team_size, workflow_stage, would_recommend). It adds slight behavioral context by tying perceived_value to asking the user, but that's also in the schema. Baseline 3 applies.

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

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

The description opens with the specific verb 'Records' and names the exact resource: 'a value moment (e.g. review_confidence, runtime_risk_found, workflow_clarity)'. It ties the tool to specific trigger contexts—'after a successful validate run on any lens (architect.validate, design.validate, or spec.validate) or a doctrine session'—which clearly separates it from sibling tools like signals.feedback or me.session_event.

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

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

It contains an explicit 'WHEN TO CALL' block with concrete conditions: after a validate returns a clearly useful result AND the user has acknowledged value, and it instructs the agent to OFFER the call when the validator's next_step says so. The 'WHEN NOT TO CALL' block is equally explicit: not silently, not on every validate, and 'do not retry within the same session' if the user declines. This fully routes the agent on when to use the tool versus when to abstain.

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