Zoning Signal

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds useful behavioral context about the nature of the output (a 'dossier projection' with a cognitive lens) and the kinds of insights it surfaces (cross-municipal dialectics, shared-infrastructure dynamics). No contradictions with annotations.

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

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

Two sentences with no filler. The first sentence states the core function, the second clarifies the lens system and differentiates from describe_place. Perfectly front-loaded and appropriately sized.

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

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

For a read-only lookup tool with an output schema, the description fully covers purpose, the cognitive lens concept, the unique value vs. alternatives, and references the right sibling for slug discovery (list_corridors in the schema). Nothing essential is missing given the tool's simplicity.

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 provides 100% coverage: both slug and lens have detailed descriptions, including an enum list and alias routing. The tool description adds only a cross-reference to describe_place's lens enum, which is redundant given the schema already lists the exact enum values. With high schema coverage, the description doesn't need to compensate.

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 action and resource: 'Return the dossier projection for a corridor, in the requested cognitive lens.' It distinguishes itself from sibling describe_place by noting that corridors surface 'cross-municipal dialectics and shared-infrastructure dynamics that no single place dossier captures.' This makes the tool's unique scope immediately clear.

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 implies when to use this tool via the alternative reference 'Same lens enum and default as describe_place' and the contrast with single-place dossiers. It doesn't explicitly say 'use describe_place for single places' or list exclusions, but the context effectively guides the agent to choose this tool for corridor-level cross-municipal analysis.

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

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

The annotations already declare readOnly, idempotent, and non-destructive hints, so safety is covered. The description adds valuable behavioral context by detailing the return structure (voxel_lead, canonical_role, class-specific cluster, graph references, provenance_chain, canonical surfaces) and explaining the stable schema_id convention, which helps an agent understand what to expect without contradicting any 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 every sentence earns its place: it lists the output fields, explains schema_id, and gives usage context. It is structured and front-loaded with the core purpose, avoiding repetition or generic 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?

With an output schema available, the description is more than sufficient. It covers what the tool does, what it returns, how to use it, and why it is the canonical cite source, making it complete for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage for the sole parameter 'slug' with examples and discovery instructions (list_entities, /entities hub). The description does not add parameter-specific guidance beyond referring to 'a named entity,' so it meets the baseline of 3 but does not exceed it.

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: 'Return the full structured dossier for a named entity' and explicitly enumerates entity types (actor, organization, ordinance, project), distinguishing it from sibling describe_* tools for corridors, meetings, patterns, places, watches, and zoning signals. It also frames it as 'the canonical citable artifact,' making its unique role clear.

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 use cases: 'Use when grounding a citation, when reasoning about an entity's full role across the corpus, or when traversing the entity graph from a single name.' It does not explicitly name alternatives or state when-not-to-use, but the context is clear enough for an agent to select this over sibling describe_* tools for other resource types.

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, non-destructive. The description adds substantial behavioral context: returns citation-stable claims, four-clock freshness, and a structured record_status block that 'prevents agents from summarizing agenda intent as completed action.' This goes beyond annotation and provides meaningful operational nuance.

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

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

The description is dense and information-rich, front-loaded with the main purpose and packed with specific return fields and caveats. Every sentence contributes value without fluff, making it appropriately sized for the tool's complexity.

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

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

Given the tool's complexity and the presence of an output schema, the description still covers return structure, semantic safeguards, and usage context. It is complete enough for an agent to select and invoke the tool correctly, including the crucial caveat about record_status preventing premature summarization.

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 fully documents both parameters, including lens aliases and fallback behavior. The description adds marginal context (mentioning the lens enum similarity and pairing with list_meetings) but does not substantially enrich parameter understanding beyond the schema.

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

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

The description clearly states the tool returns 'the full dossier projection for a meeting reading' in a requested cognitive lens, which is a specific verb+resource. It distinguishes itself from siblings like describe_place and describe_corridor by explicitly referencing the shared lens enum and the meeting-specific context.

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

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

The description gives a clear use case ('Use to ground citations in a specific meeting's reading') and pairs with discovery tools (list_meetings or meeting_index). It lacks an explicit 'when not to use' but implies meeting-specific usage, which is enough given sibling context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: the pattern is a citable entity in the corpus's entity graph, and the DefinedTerm canonical home provides a stable reference for AI agents. It also explains the output nature (full dossier with many fields). No contradictions with annotations. The description adds enough behavioral color beyond the structured hints.

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

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

The description is a single paragraph that is informative but somewhat dense, listing many fields in a run-on manner. It is front-loaded with the core action ('Return the full dossier'), but the enumeration of fields makes it longer than necessary. Every sentence earns its place, but the structure could be more concise (e.g., bullet points or shorter sentences). Not excessive, but could be improved.

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 returns a complex 'full dossier' and an output schema exists (though not shown), the description adequately covers what the dossier includes (exhibits, provenance, related entities, canonical surfaces) and the significance of the entity (citable, stable reference). It does not need to detail return values because the output schema handles that. The description is complete enough for an agent to decide when to call this tool, but it could mention the output schema's availability.

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 a single parameter 'slug' that already has a descriptive comment ('The pattern slug... Use current_named_patterns to discover available slugs'). The tool description does not add any additional meaning or formatting details about the slug parameter beyond what the schema provides. The description focuses on the overall purpose rather than parameter semantics. With full schema coverage, the baseline is 3, and the description does not significantly raise it.

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 starts with 'Return the full dossier for a named pattern' which is a specific verb+resource combination. It enumerates the exact fields included (voxel_lead, signal_status, etc.) and clearly distinguishes from sibling tools like describe_corridor or describe_entity by focusing on pattern-specific data. The purpose is unambiguous and actionable.

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 a clear usage context: 'Use when an agent needs the structured pattern data to cite or analyze.' It also references the prerequisite tool current_named_patterns for discovering available slugs. However, it does not explicitly state when NOT to use this tool (e.g., if only a summary is needed) or name specific alternatives among the sibling tools, such as list_patterns for a listing. The guidance is good but not exhaustive.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context about the default synthesis projection ("multidimensional view that holds all lenses in superposition") and how passing a single-lens value changes the output. No contradictions with annotations.

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

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

The description is three sentences, each earning its place: the first states the core action, the second explains the default behavior, and the third provides usage guidance. It is front-loaded and free of redundant content, appropriately sized for the tool's complexity.

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

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

Given the comprehensive input schema, output schema, and annotations, the description covers the essential aspects: the purpose, the default vs. single-lens behavior, and the stakeholder contexts. It does not need to explain return values (output schema exists) or provide more detail on discovery (the schema already references list_places). This is a complete picture for actionable use.

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

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

The schema provides thorough documentation for both slug and lens, including the enum, default, and alias routing (100% coverage). The description goes beyond the schema by explaining the functional impact of the lens parameter in terms of user stakes (e.g., developer, investor), which helps an agent understand when to choose a specific lens.

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

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

The description opens with a specific verb and resource: "Return the dossier projection for a city, in the requested cognitive lens." This clearly identifies the tool's function and differentiates it from sibling describe tools by focusing on cities and the lens concept.

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 clear context for when to use the default synthesis projection versus a single-lens request, stating it is "useful when the agent is acting on behalf of a user with a specific stake" and listing examples. However, it does not explicitly name alternatives or state when not to use this tool relative to 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=true and idempotentHint=true, so the tool is safe and idempotent. The description adds value by detailing exact fields returned and behavior for RESOLVED watches, which is beyond annotation scope. No contradictions exist.

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

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

The description is dense but front-loaded with the primary purpose. It contains some technical terminology that could be streamlined (e.g., 'Phase 11 Citable Contract × Phase 8 Resolution Bridge'), but each sentence provides useful context, so it earns its length.

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

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

Given the single required parameter, full schema coverage, clear annotations, and an output schema (not shown but exists), the description is complete. It explains exactly what is returned, including conditional behavior for resolved watches, without needing to repeat output schema details.

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 schema documents the 'slug' parameter well. The description adds meaning by explaining its purpose ('ground citations') and how to discover valid slugs via list_watch_items, which the schema does not provide.

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

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

The description clearly states the verb 'describe' and the resource 'watch item', and explicitly distinguishes from siblings by naming 'list_watch_items' for discovery. It enumerates specific data returned, making the tool's purpose precise and unambiguous.

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

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

The description explicitly pairs use of this tool with 'list_watch_items' for discovery, and states when to use it: 'ground citations in a specific watch's prediction or resolution'. The sibling list confirms no other tool returns the full watch dossier, providing clear guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with those. It adds value by specifying what the canonical description contains and by recommending session-level caching behavior ('once per session'), which is not in 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?

Single sentence front-loads the verb and resource, then enumerates the covered content in a compact clause. No filler or repetition; every phrase 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?

With zero parameters, an output schema present, and annotations covering safety, the description fully explains the tool's role and session-level usage. It is complete for the tool's simplicity and context.

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?

Tool accepts zero parameters, so the schema needs no elaboration. Baseline for zero params is 4; the description adds no contradictory or redundant parameter info.

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 action ('Return the canonical product description') and names the exact resource (Zoning Signal), then spells out the content domains (observatory, artifact types, regional scope, methodology). This distinguishes it from sibling describe_* tools, which target different entities.

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

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

Explicitly states 'Call once per session to ground subsequent tool calls in canonical context,' providing clear when-to-use advice. It does not mention when not to use it or name alternatives, so it stops short of a full 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds substantial value beyond this by listing in detail what metrics are returned (directional accuracy, horizon accuracy, etc.) and importantly discloses that 'Misreads are reported,' setting expectations that the data includes errors. This is rich behavioral context.

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

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

The description is front-loaded with the core purpose, then enumerates return fields, then gives usage guidance, and ends with a caveat. Every sentence adds value, and it is appropriately sized for the tool's complexity—informative without being verbose.

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 tool has an output schema and 100% schema parameter coverage, yet the description still enriches the context by explaining the return structure and strategic usage. It fully covers the 'what', 'when', and 'what to expect' aspects for an agent, making it self-contained.

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%, with each parameter (brief, corridor, jurisdiction) already described with examples. The description adds minimal extra semantic meaning beyond restating that scoping is optional. The baseline of 3 applies because the schema carries the heavy lifting for parameter explanation.

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: 'Return the observatory's public calibration scorecard' with specific aggregate accuracy metrics. It distinguishes itself from sibling tools like describe_watch or list_watch_items by focusing on historical forecasting performance rather than individual entities or simple listings.

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 a clear usage context: 'Use when an agent or user wants to assess Zoning Signal's historical forecasting accuracy before citing a current prediction.' It does not explicitly name alternatives or exclusion scenarios, but the context is strong and implies when this tool is appropriate.

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

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

Annotations already cover the safe read-only, idempotent, non-destructive profile. The description adds behavioral context by specifying 'every published' (excluding drafts) and listing the exact fields returned, which goes beyond the annotations. It doesn't discuss pagination or size, but that's less critical given the zero-parameter nature.

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

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

The description is two sentences: the first front-loads the action, the second defines the domain concept and lists return fields. Every sentence earns its place with no redundancy 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?

For a parameterless list tool with an output schema, the description is complete: it gives purpose, scope, domain definition, and return fields. The agent can confidently invoke this tool without additional context. The only minor gap is lack of explicit alternative references, but that's not necessary for completeness given the simplicity.

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 schema fully covers parameter semantics (vacuously). The description doesn't need to explain parameters, and the baseline for 0-param tools is 4. It adds no parameter-specific info, but none is needed.

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

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

The description clearly states the action ('List every published corridor page'), specifies the resource (corridor pages), and distinguishes itself from sibling tools by defining corridor as a cross-municipal economic-topology view. It also lists return fields, making the purpose unambiguous.

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

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

The description provides clear context: use this tool to get all published corridor pages. It doesn't explicitly mention when not to use it or name alternatives like describe_corridor, but the definition and list of return fields imply the appropriate use case. No exclusions are stated, so this isn't quite a 5.

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?

With annotations already declaring readOnly/idempotent, the description adds rich behavioral context: it specifies the four-class taxonomy, class-specific summary fields, cross-reference counts, and the stable schema_id format for citation. This goes far beyond what the annotations provide and gives the agent a precise mental model of the output.

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 five purposeful sentences, each serving a distinct function: purpose, return taxonomy, filters, usage clue, and schema_id semantics. It front-loads the most decision-relevant information and every sentence earns its place.

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

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

Given the output schema and complete parameter schemas, the description fully covers the remaining contextual gaps: the domain concept, cross-reference counts, and the schema_id grounding. It also addresses sibling differentiation by explicitly directing users to describe_entity for full detail, making it complete for selection and invocation.

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

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

The input schema already provides 100% coverage with detailed descriptions and examples for all three parameters. The description's mention of filters is a restatement of the schema without introducing new meaning, so 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 clearly states the tool lists every named entity in the Decoder Index, defining the resource precisely. It distinguishes itself from siblings by describing it as the 'discovery surface' for the entity graph and contrasting with describe_entity.

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 instructs 'Use as the discovery surface for the entity graph; pair with describe_entity for full structured detail,' giving a direct when-to-use directive and naming the alternative. It also enumerates the filter options, making the intents clear.

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 safety profile is covered. The description adds behavioral context by explaining that calling with no args returns the full corpus, jurisdiction filtering uses substring matching, and the response shape matches meeting_index. This goes beyond the annotations but doesn't describe pagination or output details, which are covered by the output schema.

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

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

The description is two sentences, front-loaded with the core action, and every phrase adds value (purpose, alternatives, usage scenarios). No redundancy or 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 read-only list tool with 3 optional params, an output schema, and strong annotations, the description covers the essential behavioral aspects, usage guidance, and relationship to siblings. It doesn't need to explain return values given the output schema, and the usage context is fully addressed.

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?

All three parameters have thorough descriptions in the schema (100% coverage), including examples and inclusive date semantics. The description primarily restates this information ('optionally filtered by date range or jurisdiction substring') and adds the usage pattern of no-args invocation. Since the schema does the heavy lifting, the description adds minimal new param meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Return meeting readings across all cities' and explicitly differentiates from sibling tool meeting_index by noting it has the same response shape but no required parameters. It also specifies its filtering capabilities (date range, jurisdiction substring), making it distinct from other list tools.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to enumerate the full meeting record or scan across cities by date range.' It also contrasts with meeting_index, implying when this tool is preferable (when no required parameters are needed). This meets the criterion of explicit usage context.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint, so the main behavioral expectation is that this is a safe, read-only operation. The description adds helpful context about the return fields and version tracking (Phase 12), though it doesn't detail any empty-state behavior or rate-limiting implications.

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 yet efficient, with front-loaded purpose and usage context. It could trim the explicit version note and schema loader comment, but overall each sentence adds value and no word 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?

Given zero parameters, a complete output schema, and comprehensive annotations, the description covers all needed aspects: purpose, usage context, return fields, and pairing advice. It leaves no gaps for an agent to guess.

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 no parameters and schema description coverage is 100%, so there is nothing left to clarify. The description adds no parameter information because none exist. 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 clearly states it lists all named patterns in the Pattern Atlas, distinguishing it from sibling tools like describe_pattern (which provides details on a single pattern) and list_* siblings. It specifies the tool returns a defined set of fields, making the resource and action unambiguous.

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

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

The description explicitly calls this the 'discovery surface' for the Pattern Atlas and suggests pairing with describe_pattern for full details, giving agents a clear when-to-use guide. It also notes it was renamed from current_named_patterns, which helps avoid confusion with legacy terminology.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds transparency about what the tool returns (specific fields, URL) and the option to filter by state, going beyond the annotations to disclose behavioral details such as the absence of user/workspace filtering. No contradictions exist.

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

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

The description is concise at four sentences, each serving a distinct purpose: main function, optional filter, field listing, and usage guidance. The front-loaded first sentence immediately states the core action and scope, making it efficient for an agent to parse.

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 (0 required params, output schema present) and rich annotations, the description is largely complete. It covers purpose, filter, output fields, and usage context. The only minor gap is that it doesn't mention pagination or rate limits, but for a straightforward list tool with one parameter, this is adequate.

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 fully documents the single parameter (state) with a clear description. The description reinforces this by mentioning the optional state filter, adding context about its purpose (discovering coverage) but not adding new syntax or format details beyond the schema. Given maximum schema coverage, a score of 4 is appropriate.

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

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

The description clearly states the tool lists every place dossier the observatory publishes, differentiating it from siblings like describe_place which drills into a specific place. It specifies the exact fields returned (city, state, slug, etc.) and mentions the optional filter by state, leaving no ambiguity about what the tool does.

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

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

The description explicitly advises using this tool before calling describe_place to discover available place-level coverage, providing a clear usage sequence. It also includes a history note (renamed from list_cities) that helps an agent understand consistency with the content-type vocabulary, though it doesn't explicitly state when not to use it or list alternatives with exclusions—the purpose is sufficiently narrow that no further guidance is needed.

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 explicit. The description adds context about the nature of items (forward calendar, condition-triggered milestones) but does not disclose additional behavioral traits like defaults, pagination, or response format. It does not 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?

The description is two sentences and front-loads the core purpose. It is concise, but the phrase 'from any cognitive position' is abstract and adds little practical value. Overall, it is efficient and easy to scan.

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 five optional parameters, an output schema, and strong annotations (read-only, idempotent), the description covers the essential aspects: what is returned, what filters are available, and the intended use. It does not need to explain return structure (output schema exists) or safety (annotations cover it). A little more detail about default status behavior would make it fully complete, but for a list tool this is 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 input schema has 100% coverage, with descriptions for every parameter (status, horizon, place, corridor, brief). The description repeats the filter categories at a high level ('status (pending / resolved / obsolete), horizon (imminent / near-term / structural), or scope (place / corridor / brief)') but adds no new syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Return The Watch — the field's forward calendar of pending events, scheduled hearings, regulatory sunsets, and condition-triggered milestones.' This makes clear what the tool does and distinguishes it from sibling describe_* and list_* tools by focusing on tracking items rather than describing a place or entity.

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 says 'Use to surface what the field is watching from any cognitive position,' providing clear context for when to invoke the tool. It does not explicitly name alternatives or exclusions, but the use case is evident. A named alternative or exclusion would strengthen it, but the guidance is sufficient for an agent to choose this tool over 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description enhances this by explaining the output's nature (plain-English, signal extraction, entity mapping) and the temporal scoping, adding context beyond structured annotations.

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

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

Three sentences, each earns its place: function, definition of key term, and usage context. Front-loaded and free of redundant wording.

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 read-only filtered tool with full schema and output schema, the description is complete. It covers purpose, semantic meaning, temporal scope, and usage, with annotations covering safety and idempotency.

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 city, to_date, and from_date fully documented. The description adds no new parameter-level detail beyond restating the optional date range, providing only marginal added value over 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 meeting readings for a specific city with an optional date range, and defines 'meeting reading' as a plain-English read with signal extraction and entity mapping. This distinguishes it from siblings like list_meetings or describe_meeting by scope and depth.

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 final sentence provides an explicit use case: 'Use to drill from a city or corridor into the temporal record.' While it lacks explicit exclusions or named alternatives, the context is clear enough to guide selection among sibling tools.

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, non-destructive. The description adds substantive behavioral context: cosine similarity ranking, the 1024-dimensional embedding space (Voyage AI 4 + pgvector), result count limit (top 12), similarity threshold (0.55), and resolved URL per hit. This goes well beyond the annotations and sets clear expectations for the agent.

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 and every sentence delivers distinct value: corpus scope, embedding/ranking details, usage guidance, and output shape. It is slightly long but not wasteful; the density is appropriate for a complex semantic search 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?

With an output schema present, the description still covers return fields (type, title, similarity, resolved URL), result limit, threshold, and coverage. Given a single-parameter tool with rich annotations and an output schema, the description is fully complete for an agent to invoke and interpret results 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?

Although schema coverage is 100%, the description adds practical meaning to the 'q' param: it accepts a phrase, entity name, or thematic concept, and explains that asymmetric query-time embedding handles short queries cleanly. This enriches the schema's description and gives the agent actionable guidance on crafting queries.

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 'Semantic search across the full corpus' and enumerates the exact sources (place dossiers, corridor signals, meeting readings, named-pattern briefs). It distinguishes itself from sibling describe/list tools by explicitly stating it is for when the agent does not know the canonical slug or title in advance. This is a specific verb+resource+scope with 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?

Explicitly states when to use: 'Use when the agent does not know the canonical entity slug or named-pattern title in advance.' This also implies when not to use (when you do know, use describe/list tools). It further clarifies what the tool returns (type, title, similarity, URL) and the technical constraints (threshold 0.55, top 12), giving the agent sufficient context to decide.

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 provide no safety hints (all false), so the description carries the burden of disclosing behavior. It does so richly: submissions auto-attach the prior 10 invocations, operators triage and surface notable feedback at /agent-observatory, and categories are explained. This goes beyond the binary annotation flags and gives the agent a clear model of side effects.

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, then lists categories, auto-attachment behavior, triage process, and rationale. It is slightly longer than necessary (repeating category definitions from the schema) but every sentence adds context about process or intent, making it efficient and well-structured.

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

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

Given the complexity of a feedback tool with six parameters and an output schema, the description covers the essential context: what feedback is for, what categories exist, how the submission is augmented (auto-attach), and what happens afterward. The output schema handles return-value documentation, so no gap exists.

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 schema itself already explains each parameter thoroughly. The description adds the context that 'no need to repeat what you tried' due to auto-attached invocations, and it elaborates category meanings, but these are largely redundant with the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource pair: 'Submit feedback to the observatory's operators about the MCP tool surface.' It clearly distinguishes from sibling tools (which are all describe/list/search operations) by being the only submission tool. The 'active counterpart to the passive invocation log' further differentiates its purpose.

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

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

The description provides clear context for when to use this tool ('when you encounter a gap, error, praise, suggestion, or citation request') and contrasts it with the passive log ('no need to repeat what you tried'). It lacks an explicit alternative not-to-use statement, but the sibling tool set contains no other feedback pathway, so this is adequate.

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