Zoning Signal

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

The annotations already establish that this is read-only and idempotent. The description adds meaningful behavioral context beyond that: the output is a lens-dependent projection, the lens behavior is shared with describe_place, and corridor projections have unique cross-municipal analytical scope.

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 with no filler. The core action is front-loaded, the lens behavior is clarified in the second sentence, and the distinguishing value of corridor projections is stated in the third without redundancy.

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

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

The tool is simple, has an output schema, and its annotations cover safety and idempotency. The description provides sufficient differentiation from sibling tools and enough conceptual framing 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?

Schema description coverage is 100%, and the schema already documents lens enums, defaults, aliases, and slug discovery via list_corridors. The description's mention of a 'cognitive lens' and 'same lens enum' adds conceptual flavor but not semantic detail 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 names a specific verb-resource pair: returning the dossier projection for a corridor in a chosen cognitive lens. It also differentiates this tool from its closest sibling by invoking describe_place and explaining that corridor projections capture cross-municipal dialectics that place dossiers cannot.

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 clear contextual guidance by contrasting corridor-level projections with place-level dossiers and referencing describe_place's lens enum/default. It implies when a corridor should be used over a place, though it does not explicitly list exclusions or other 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 readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds valuable context beyond that: the stable schema_id as the canonical cross-page reference, the detailed return structure, and the relationship to trace_connection. This enriches the agent's understanding of what the call returns and how it fits into the broader corpus.

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 efficiently organized: purpose first, then a detailed but structured list of return components, then usage guidance and differentiation. Every sentence contributes either to purpose, usage, or differentiation, with no fluff or repetition. The length is justified by the complexity of the output.

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 parameter, full schema coverage, and existing output schema, the description is complete. It explains what the dossier contains, when to use it, and how it differs from trace_connection. The tool is a read operation with annotations covering side effects, so 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?

The schema provides 100% coverage of the single parameter (slug) with examples and a pointer to list_entities. The description adds the Decoder Index hub mention, but that is already present in the schema description. The description does not add new parameter semantics beyond the schema, so the 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?

States a specific verb ('Return') and resource ('full structured dossier for a named entity'), enumerates the exact components returned, and explicitly contrasts with trace_connection. An agent immediately knows what this tool does and how it differs from the sibling.

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 use cases ('grounding a citation, reasoning about an entity's full role, traversing the entity graph') and directly names the alternative trace_connection with a clear distinction ('what one node touches' vs 'what joins two'). This leaves no ambiguity about when to choose this tool.

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

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

Beyond the readOnly/idempotent annotations, the description details the returned blocks (lens-projected body, frontmatter, claims[], freshness, record_status) and, crucially, explains that record_status prevents agents from treating agenda intent as completed action. This is exactly the kind of behavioral context that helps an agent use results correctly.

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 a minimal description, every sentence carries information: the first sentence states the core action, subsequent sentences enumerate outputs and end with a practical warning and usage direction. It is front-loaded and free of 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?

The combination of annotations, a 100%-covered schema, an output schema, and this description gives an agent everything needed to select and call the tool: what it returns, when to use it, how to discover slugs, and the shared lens semantics with siblings. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by naming the seven stakeholder lenses and stating the lens enum/default is the same as describe_place/describe_corridor. It also reinforces slug discovery with list_meetings/meeting_index, going slightly 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 opens with a specific verb and resource: 'Return the full dossier projection for a meeting reading' and later says 'Use to ground citations in a specific meeting's reading.' This clearly differentiates describe_meeting from siblings like describe_place/describe_corridor by the meeting resource.

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

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

It gives a clear use case ('Use to ground citations in a specific meeting's reading') and points to list_meetings/meeting_index for discovery, plus notes the lens enum is shared with describe_place/describe_corridor. It stops short of explicitly saying when not to use sibling describe tools, so it is not 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?

Annotations already declare the tool read-only, idempotent, and non-destructive; the description adds useful context by specifying that it returns the full dossier and canonical stable references. No contradiction exists between the description and 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?

Three dense sentences front-load the return contract, then usage, then conceptual context. The long list of dossier contents is justified because it defines what 'full dossier' means and helps an agent decide whether to call this tool, though it is slightly 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?

For a single-parameter read tool with an output schema, the description covers purpose, contents, and stable-reference context well. A minor caveat is that the schema references 'current_named_patterns' while the sibling list includes list_patterns, which could slightly confuse slug discovery.

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 covers the single slug parameter 100%, including an example and a pointer to discover available slugs. The description adds little beyond calling it a 'named pattern,' so the schema carries the semantic weight.

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 ('Return the full dossier for a named pattern') and enumerates the dossier contents, making the tool's purpose clear. It is implicitly distinct from list_patterns as a detailed single-pattern lookup, but it does not explicitly name or compare against a sibling 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?

The description gives an explicit usage trigger: 'Use when an agent needs the structured pattern data to cite or analyze.' It does not provide exclusions or point to alternatives such as list_patterns for broader discovery, so it stops short of 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by explaining the default 'synthesis projection (the multidimensional view that holds all lenses in superposition and names the dialectics)' and the dispatch behavior when a single lens is passed. 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?

Two sentences with the core action and default behavior front-loaded in the first sentence, followed by single-lens usage and stakeholder use-cases in the second. Every clause earns its place; 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 two-parameter tool with an output schema present and rich annotations, the description fully covers lens semantics, defaults, and when to use it. Return values need not be explained since an output schema exists. Nothing an agent needs to call this 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 elevates this by explaining the meaning of the lens parameter (synthesis as the superposition of all lenses vs. a focused cognitive position) and mapping lenses to user stakes. The slug is already well documented in the schema with an example and pointer to list_places.

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' — and introduces the tool's distinguishing feature, the cognitive lens that projects different viewpoints. Being place-scoped (vs. corridor/entity/meeting siblings) makes its 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?

It enumerates concrete triggering contexts ('acting on behalf of a user with a specific stake: developer underwriting, investor thesis, broker client argument...'), telling an agent when this tool is the right call. It does not explicitly name sibling tools or state when not to use it, so exclusions are absent, though the provided context is strong.

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 false. The description adds behavioral nuance by detailing the special handling of RESOLVED watches (outcome cluster, lesson surfacing as claim_id) and the compound contract reference. This goes beyond annotations, though it does not discuss side effects or auth, which are already covered.

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 dense paragraph that front-loads the purpose and then lists return fields, resolved handling, and usage. It is comprehensive but slightly verbose with technical jargon (e.g., 'Phase 11 Citable Contract × Phase 8 Resolution Bridge compound'). No redundant sentences, but could be tighter.

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 goes beyond what is required by explaining the return structure, the resolved-watch special case, and the citation-grounding use case. It also names the companion discovery tool. An agent has all necessary context 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 schema covers the single parameter (slug) fully with an example and discovery instruction. The description does not add new semantic detail about the parameter itself; it merely reinforces the discovery method already in the schema. Baseline of 3 applies due to 100% schema coverage.

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

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

The description states a specific verb and resource: 'Return the full dossier for a watch item'. It clearly identifies the resource (watch) and the action (return dossier), and differentiates from siblings by mentioning list_watch_items for discovery. The purpose is unambiguous and distinct.

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 states when to use this tool: 'Use to ground citations in a specific watch's prediction or resolution' and pairs it with list_watch_items for discovery. This gives a clear use case and directs to the alternative for finding watches, leaving 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=false, so the safety profile is covered. The description adds meaningful behavioral guidance beyond annotations: it frames the tool as a canonical context provider and recommends calling it once per session.

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 states the purpose and content, the second gives the usage instruction. Every sentence earns its place and the key information is front-loaded.

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

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

For a zero-parameter, read-only, idempotent tool with an output schema, the description fully covers what the tool returns, what it contains, and when to call it. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameters. The baseline of 4 applies because no parameter documentation 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 uses a specific verb ('Return') and names the exact resource ('canonical product description for Zoning Signal'), then lists the content covered. This clearly differentiates it from sibling describe_* tools by tying it to Zoning Signal specifically.

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 instructs to 'Call once per session to ground subsequent tool calls in canonical context,' providing clear usage context. It does not explicitly mention when not to use it or name alternatives, so it stops short of 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?

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds transparency by specifying the exact return fields, including a note that 'Misreads are reported,' which indicates the tool includes errors in its output. This goes beyond the annotation baseline and provides useful 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 moderately long but well-organized, starting with the core purpose, then listing return fields, then optional scoping, and ending with usage guidance. It is informative without being rambling, and the key information is front-loaded.

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

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

For a read-only query tool with an output schema, the description covers the purpose, when to use it, what it returns, and optional parameters. It also mentions the reporting of misreads, which is an important nuance. There are no obvious gaps that would prevent an agent from calling 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?

Schema coverage is 100%, so all three parameters have descriptions. The description adds a bit of context by mentioning optional scoping and the concept of a 'constituent set' for corridors, but it doesn't substantially extend what the schema already documents. 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: returning the observatory's public calibration scorecard, which aggregates historical forecasting accuracy metrics. It distinguishes itself from sibling tools by focusing on accuracy data rather than entity descriptions or listings, and explicitly names the types of metrics returned.

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

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

The description includes a clear 'Use when' clause: when assessing Zoning Signal's historical forecasting accuracy before citing a prediction. It also notes optional scoping to jurisdiction or corridor. It doesn't explicitly list alternatives or exclusions, but the use case is well-defined and distinct from 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 cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: only published pages are returned, the result is exhaustive ('every'), and the response includes name, slug, constituent cities, primary axis, and URL. No statement contradicts 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?

Three sentences with no waste: the action is front-loaded, the middle sentence adds the domain definition needed to differentiate the tool, and the final sentence lists return fields. Every sentence earns its place and the structure is 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?

For a zero-parameter, read-only list tool with a provided output schema and comprehensive annotations, the description supplies all remaining relevant context: the corridor concept, published-only scope, exhaustive listing behavior, and the fields returned. Nothing an agent needs to correctly select or invoke this tool 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 input schema has zero parameters and schema description coverage is 100%, so the baseline for no parameters applies. There are no parameter semantics to clarify, and the description does not need to compensate for any schema gap.

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 ('List every published corridor page') and defines what a corridor is ('cross-municipal economic-topology view'), clearly distinguishing this from sibling list tools such as list_places, list_entities, and list_patterns. The scope ('every published') is explicit and immediately usable.

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 does not explicitly name alternatives or say when not to use the tool, but its definition of corridor as a cross-municipal, cross-jurisdiction concept makes the intended use obvious and separates it from the other list tools. For a zero-parameter tool, this level of contextual routing is sufficient.

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

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

Annotations already mark the tool as read-only and idempotent, so the description does not need to restate safety. It adds substantial behavioral context: class-specific summary fields, cross-reference counts, and a stable schema_id pattern useful for citation grounding.

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 purpose and then delivers output shape, filter options, usage guidance, and identifier semantics in a dense but non-redundant structure. Every sentence earns its place, and the alternates are clearly separated.

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

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

Given the output schema exists and annotations are rich, the description is complete for selecting and invoking the tool correctly. It covers output semantics, filters, sibling relationship, and a stable reference convention, so no critical runtime context is missing.

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

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

Schema coverage is 100%, and each parameter already has a rich schema description. The tool description only restates the filter names ('entity_class, place (jurisdiction), or search substring') without adding meaningful detail beyond what the schema provides, so it stays at 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?

States a specific verb and resource: 'List every named entity in the Decoder Index.' It also defines the resource's role ('smallest citable unit of authority') and names the exact taxonomy returned, which makes it easy to distinguish from siblings like 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?

The description explicitly says to use this as 'the discovery surface for the entity graph' and to 'pair with describe_entity for full structured detail.' This gives an agent clear guidance on when to use this tool versus the natural sibling alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the response shape matches meeting_index, jurisdiction filtering is a substring (not exact match), and calling with no args returns the full corpus. This goes beyond the annotations and helps the agent understand semantics.

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 with no fluff. The main purpose is front-loaded, then the optional filters, then a clear usage directive. Every sentence earns its place, and the sibling reference is included naturally.

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 and annotations covering safety, the description covers all essential information: what it does, when to use it, how parameters behave, and how it differs from meeting_index. Nothing critical is missing 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 coverage is 100%, so each parameter is documented. The description adds extra meaning: clarifies that jurisdiction is a case-insensitive substring, and that omitting parameters yields the full corpus. It also implies date range filtering without exact match. This supplements the schema meaningfully.

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: 'Return meeting readings across all cities'. It differentiates from sibling meeting_index by noting 'Same response shape as meeting_index but with no required parameters', so an agent can immediately see the distinction.

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 when you need to enumerate the full meeting record or scan across cities by date range.' It also explains when to call with no args vs. with a jurisdiction substring, and implicitly contrasts with meeting_index by noting the required-parameter difference.

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 meaningful context by stating the tool returns 'every named pattern,' enumerating the returned fields, and explaining the canonical pattern URL. It does not mention pagination or freshness, but the output schema and strong annotation coverage reduce the burden.

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?

Purpose and usage are front-loaded and clear, but the description includes verbose historical and implementation details such as 'Phase 12 renamed it,' 'Phase 9 DefinedTerm canonical home,' and 'loader: getAllContent("pattern").' These add context but are not essential for an agent to call the tool, and the URL pattern is repeated.

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 list tool with an output schema and rich annotations, the description covers purpose, scope, return fields, canonical URL convention, and sibling relationship. Nothing essential for correct invocation is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description still adds semantic value by defining what a 'named pattern' is and what fields will be returned, which helps an agent interpret results even without an input schema to document.

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: 'List every named pattern in the Pattern Atlas.' It defines 'named pattern' concretely with an example and names the sibling describe_pattern, so an agent can distinguish this discovery tool from detail-lookup tools and other list_* siblings 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 explicitly says 'Use as the discovery surface for the Pattern Atlas; pair with describe_pattern for full dossier detail.' This gives clear when-to-use guidance and points to the alternative for deeper detail. It does not explicitly contrast with semantic_search or other list tools, but for a list-all discovery tool the guidance is strong.

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 value by enumerating return fields (city, state, slug, signal strength, signal direction, dossier URL), which is behavioral context beyond the schema. 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 purpose is front-loaded, but the description includes dense implementation details (loader function getAllContent, URL patterns, rename history) that are not needed for invoking the tool. These extra sentences could be trimmed without losing value for the 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?

With a simple single-param schema, output schema present (which covers return values), and the description summarizing return fields plus usage guidance, the definition is sufficiently complete for an agent to call the tool correctly. Minor gaps like pagination aren't relevant here.

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

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

Schema coverage is 100% and the parameter description already covers filtering by state and omission semantics. The tool description repeats 'Optionally filter by state' without adding new constraints or nuance, so it adds no 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 states 'List every place dossier' – a clear verb+resource – and distinguishes this tool from siblings like list_corridors/list_entities by the resource type 'place'. It also names the follow-up describe_place, making its role 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?

Explicitly says 'Use to discover the available place-level coverage before calling describe_place', giving a clear when-to-use. It does not explicitly exclude alternatives or compare to other list tools, but the context is sufficient for an agent to infer appropriate 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context by defining the content (pending events, hearings, sunsets, milestones) and the filter axes, which goes beyond what annotations state. No hidden behaviors are left undisclosed.

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 tightly written sentences. The first states the resource and its contents; the second lists filters and the intended use. No wasted words, and the core purpose is front-loaded before the filter details.

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

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

For a read-only listing tool with zero required parameters, a rich output schema, and fully documented parameters, the description is complete. It tells the agent what is returned, how to filter, and when to use it. Nothing critical is missing 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 coverage is 100%, so every parameter is already documented in the schema, including enum values and defaults. The description restates the filter categories (status, horizon, scope) but adds no new syntax or semantics beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 ('Return The Watch') and immediately clarifies what that means: a forward calendar of pending events, hearings, sunsets, and milestones. It distinguishes itself from sibling list/describe tools by naming its unique subject (the observatory's watch items) and explicitly listing the filter dimensions.

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 closing line 'Use to surface what the field is watching from any cognitive position' gives a clear usage context. It does not explicitly contrast with alternatives like describe_watch or list_places, but the purpose is unambiguous enough that an agent can infer when this tool is appropriate versus others.

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 establish readOnly, idempotent, non-destructive safety. The description adds substantial behavioral context beyond that: the reciprocal-rank fusion of full-text/title/embedding lists, query operator syntax ('quotes', OR, -word), response fields (similarity, matched, scope, evidence, note), the weak_match deprecation and its 2.4.0 removal, and the 25-jurisdiction/5-county coverage limit. This is exactly the kind of operational detail annotations cannot 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?

The description is long (~200 words) but every sentence carries information: coverage, ranking, response contract, deprecation, result cap. It is well front-loaded with the core action and resource list, followed logically by mechanics, response shape, and caveats. Slightly dense, but the complexity of a fused-ranking search tool 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?

With a rich output schema present, the description still explains the response contract (similarity, matched, scope, evidence, note, coverage), the deprecation path, geographic/jurisdictional coverage, and the 'Top 12' result cap. For a single-parameter search tool, nothing an agent needs 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 coverage is 100% and the schema already explains the q parameter well (names/numbers/questions, word-matching semantics, 500-char limit). The description adds value beyond the schema by documenting the query operators (quotes, OR, -word) and enumerating the concrete input types (parcel id, alternate key, ordinance/resolution number) — genuine supplementary 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?

States a precise verb-resource pair — 'Search every record by exact words and by meaning at once' — and enumerates the exact record types covered (meeting agendas, place dossiers, corridors, patterns, entities, watch items) and the kinds of queries it resolves (case numbers, parcel ids, addresses, people). This clearly distinguishes it from the resource-specific describe_*/list_* siblings, which retrieve single known resources rather than searching across all.

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 makes usage context clear by specifying scope ('Search every record') and query styles (names, numbers, questions), which implies it is the cross-cutting lookup tool versus the per-resource siblings. It does not explicitly name alternatives with when-not conditions, but the resource enumeration and 'Finds a case... or a plain-language question' framing make the intended usage unambiguous.

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

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

The annotations are all false hints, so the description carries the full behavioral burden. It discloses the key side effect—auto-attaching the prior 10 invocations from the MCP-Session-Id—and what happens after submission (operators triage and surface notable feedback). This gives the agent a concrete model of the tool's behavior beyond what any structured field provides.

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 opens with the core purpose and includes compact category definitions, but the category parentheticals partially duplicate the schema descriptions. The extra behavioral details about session attachment and operator triage justify 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 feedback-submission tool with six parameters, complete schema descriptions, and an output schema, this description covers purpose, category selection, and post-submission side effects. Nothing an agent needs to invoke the tool correctly is missing, and the auto-attached invocation context is a critical detail absent from schema and annotations.

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 each of the six parameters is already well documented in the schema. The description mostly restates the category values rather than adding new parameter-specific meaning; the additional value it provides is behavioral context, not parameter semantics. Baseline 3 applies.

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

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

The description states a specific action ('Submit feedback'), a recipient ('observatory's operators'), and a subject ('MCP tool surface'). It also distinguishes the tool as the 'active counterpart' to the passive invocation log, which clearly separates it from all sibling read/list/describe 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 category definitions give clear guidance on when to use each type of feedback, and the final sentence frames this as the mechanism for evolving the observatory. It does not explicitly name alternatives or state when not to use it, but no sibling tool competes with this function, so the usage context is 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 only cover read-only/idempotent/closed-world safety, yet the description discloses the ranking logic (widest-waypoint degree), uniqueness and provenance columns, filter interactions (crossing holds no two-hop minuted route), fragmentation reporting instead of bare no_path, and explicit undetermined areas (vote outcomes, direction, the 347 unlinked meeting records). This is far 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?

Purpose and the three modes are front-loaded, and the paragraphs are cleanly ordered (modes, substrate, ranking rationale, filters, limits). It is dense and carries a large volume of corpus statistics that push length well past what tool selection strictly requires, but little is truly redundant.

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, filter-heavy graph tool with a rich output schema, the description supplies the substrate model, ranking semantics, filter interactions, and honest capability limits. An agent has everything needed to call it correctly; return-value detail is rightly left to 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 baseline is 3, but the description adds genuine meaning: evidence is named 'the largest single lever' with fragmentation consequences, crossing's jurisdiction interaction is explained, limit's refuse-not-clamp behavior is stated, and undirected `to`/`from` normalization is called out. It goes past restating 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?

States a specific verb+resource (trace how two named things connect, report specificity) and immediately enumerates the three operating modes (from+to, from alone, neither). It is clearly distinguishable from the sibling describe_*/list_* tools, which return dossiers and inventories rather than routes.

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 maps each invocation shape to its purpose ('Give from and to for the shortest route... from alone to rank... neither to rank the corpus'), and names the alternatives (describe_entity, describe_meeting, semantic_search) with the case each serves. When-to-use is fully spelled out.

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