Motley MCP Server

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

Annotations already mark the tool as readOnly and idempotent. The description adds behavioral details: it returns a per-metric matrix with each neighborhood's band and the per-metric leader, and notes that unscored codes are dropped. This adds value beyond annotations without contradiction.

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 purpose, and every word adds value. It is concise 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 tool has only one parameter and a simple array input, the description adequately explains what to pass and what to expect in return. An output schema exists but is not detailed here; the description covers the essential information. It is complete for its complexity.

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

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

Schema coverage is 100% with a description for the single parameter. The description adds meaning by stating that codes should come from 'search-neighborhoods' and that unscored codes are dropped, enhancing the schema's minimal description.

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

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

The description clearly states the tool compares 2–6 NYC neighborhoods side by side across 9 specific family-fit metrics. It uses a specific verb ('compare') and resource ('neighborhoods'), and distinguishes from siblings like 'rank-neighborhoods' and 'search-neighborhoods' by focusing on side-by-side per-metric comparison.

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 when to use the tool (to compare neighborhoods) and what input to provide (array of NTA codes). It hints at a prerequisite by referencing 'from search-neighborhoods' but does not explicitly state when not to use it or list alternatives, though the sibling tools are provided in 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 and idempotentHint=true, so the agent knows it's safe and idempotent. The description adds that the output includes a 'plain-English explainer plus its typical deadline window', providing useful behavioral context beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no extraneous information. Every sentence earns its place.

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

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

For a simple tool with one required parameter and an output schema (implied), the description adequately explains what to input and what to expect. It does not cover error cases like invalid keys, but that is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the exact keys and clarifying that 'method' can be either a method key or an early entry point, which goes beyond the schema's description.

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

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

The description clearly states the verb 'Explain' and the resource 'NYC admission entry point or method'. It lists specific valid inputs, distinguishing this from sibling tools like 'get-admissions-methods' which likely lists methods rather than explaining one in detail.

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 tells the agent to 'Pass a method key or early entry point' and provides the complete list of valid values. It does not explicitly contrast with siblings or state when not to use it, but the purpose is clear enough for typical use.

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 read-only, idempotent, and open-world behavior. The description adds valuable context beyond annotations, such as geocoding via OpenStreetMap, NYC bounding, and the inclusion of a 'family-fit summary' in the output. There is no contradiction.

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 sentence states the core purpose and output, the second provides usage advice. Every sentence is useful and there is no extraneous information.

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

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

The description lists the output fields (NTA code, name, borough, family-fit summary). Given that an output schema exists, it does not need to explain return values in detail. It is complete for the tool's purpose, though it does not mention error handling for invalid addresses.

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 all three parameters with descriptions (100% coverage). The description adds context by stating the relationship between parameters (address OR lat+lng) and notes that geocoding is NYC-bounded. This provides additional semantic value beyond the schema.

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

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

The description explicitly states the verb ('Find'), the resource ('NYC neighborhood (NTA)'), and the inputs (address or lat+lng). It also lists the output fields. This clearly differentiates it from sibling tools like 'get-neighborhood' or 'search-neighborhoods', which serve different purposes.

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 usage context: 'Use this to turn a real-world location into a neighborhood you can pass to the other tools.' It also clarifies that either an address or lat+lng should be provided. While it doesn't explicitly mention when not to use it, the purpose is well-scoped.

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

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

The description adds value beyond annotations by explaining the last_refreshed field's meaning ('when we last verified it with Foursquare'). Annotations already indicate readOnlyHint and idempotentHint, and the description does not contradict them.

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

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

The description is two sentences long: first sentence clearly defines purpose, second sentence covers usage details. Every word adds value, no redundancy.

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

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

Given the tool has only 4 parameters, full schema coverage, output schema, and annotations, the description sufficiently covers usage patterns (pagination, count_only), and an important output field. No major gaps for typical usage.

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 good parameter descriptions, but the description adds significant context: how count_only and limit/offset work together, and that last_refreshed is a verification timestamp. This complements the schema effectively.

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

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

The description clearly states 'Get kids' activities and businesses in a neighborhood' with specific examples like classes, sports, arts, and tutoring. The verb 'Get' and resource are explicit, and the reference to Foursquare data distinguishes it from sibling tools like get-schools or find-neighborhood.

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 guidance on using count_only for category breakdown and limit/offset for pagination, including that the response reports total/returned. It lacks direct comparisons to sibling tools but the context is clear enough for 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 indicate read-only and idempotent behavior. The description adds sourcing from MySchools and data availability caveats (e.g., zoned schools usually have none), which is helpful beyond annotations.

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

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

Two sentences, front-loaded with action and output, followed by usage notes. Every sentence is purposeful with no unnecessary words.

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

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

For a simple one-parameter tool with output schema and clear annotations, the description fully covers purpose, usage, limitations, and return values. No gaps.

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

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

Schema coverage is 100% with a good description for 'dbn'. The description reinforces that the DBN comes from get-schools, adding minimal extra value beyond the schema.

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

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

The description clearly states the tool gets admissions competitiveness for one school, specifying metrics like seats vs. applicants, applicants-per-seat, and competitiveness tier. It distinguishes from sibling tools like get-admissions-methods by focusing on demand rather than methods.

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 to pass a school DBN from get-schools and notes that data is mostly for screened/choice schools, implying when not to use. Provides clear context for effective use.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds transparency by noting the tool provides live program counts and optional filters to narrow those counts, and the 'Knowledge only' tag reinforces no 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 two concise sentences, front-loading the core purpose (listing all methods) and efficiently adding filter behavior and the 'Knowledge only' cue. No unnecessary words.

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

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

Given the presence of an output schema and annotation richness, the description is fully adequate. It covers what the tool returns (all methods, windows, program counts) and how filters work, leaving no gaps for an agent to invoke 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 covers both parameters (band, governance) with enum descriptions. The description adds meaning beyond the schema by stating that these filters 'narrow that count' (the live program count), clarifying their effect on the output.

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 explicitly states it retrieves the full NYC school-admissions reference, listing all entry points and methods (3-K, Pre-K, Kindergarten, Gifted & Talented, and 8 middle/high methods) with application windows. This clearly defines the tool's purpose and distinguishes it from sibling tools like explain-admissions-method or get-admissions-demand.

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 indicates the tool is for knowledge only, but does not provide explicit guidance on when to use it versus alternatives (e.g., using explain-admissions-method for a single method, or get-admissions-demand for demand data). The intended use case is implied but not stated.

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

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

Annotations indicate readOnlyHint and idempotentHint, so the agent knows it's safe. The description adds behavioral context by explaining the underlying 9-dimension vector (family density, wealth, etc.) and that it returns similarity scores. No contradictions.

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

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

The description is short (two sentences), front-loaded with the core action, and every word adds value. No redundancy.

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

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

Given an output schema exists (though not shown), the description adequately covers the tool's behavior. It mentions the vector and similarity scores. Could be improved by explaining NTA codes, but acceptable.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context about the vector, but doesn't provide additional syntax or format details beyond the schema. 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 precisely states the tool's purpose: finding similar neighborhoods based on a 9-dimension score vector. It clearly distinguishes from sibling tools like compare-neighborhoods or search-neighborhoods by specifying the similarity mechanism.

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 (finding similar neighborhoods), but does not explicitly mention when not to use it or suggest alternative tools like compare-neighborhoods for direct comparisons. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint true. Description adds meaningful behavioral detail: the tool returns demographics, scores (raw and banded), location, and cached editorial blurbs, enhancing transparency beyond annotations.

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

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

Two sentences with no waste. First sentence states purpose and contents; second gives usage tip. Front-loaded with key action ('Get full 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?

Given the tool's complexity (multiple data categories), the description covers all needed aspects for selection. Output schema exists for return values, so description doesn't need to detail them. Complete for decision-making.

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?

Only parameter (nta_code) is fully described in schema with example. Description adds value by clarifying that the nta_code comes from search-neighborhoods, providing usage context. Schema coverage is 100%, so baseline is 3; description adds enough to raise to 4.

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

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

Description clearly specifies the tool retrieves full details for a single NYC neighborhood, listing categories (demographics, scores, location, interpretation). It distinguishes from siblings like search-neighborhoods and get-neighborhood-summary by stating it's for a single neighborhood with detailed info.

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 to use nta_code from search-neighborhoods, implying this tool is for detailed single-neighborhood lookup after initial search. While it doesn't state when not to use, the context with sibling tools makes it 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 and idempotentHint, so the safe, non-destructive nature is clear. The description adds value by mentioning 'cached editorial blurbs', indicating that results may be cached, and that raw scores are still available.

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 purpose, and contains no extraneous words. Every sentence adds meaningful context.

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

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

Given the tool has an output schema, the description adequately summarizes the output (verdict, score bands, blurbs, raw scores). It covers the key aspects for a simple one-parameter tool, though it could mention that output formatting is designed for families.

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?

With only one parameter (nta_code) and 100% schema description coverage, the baseline is 3. The description does not add additional semantic detail beyond what the schema already provides (e.g., format 'BK0101').

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 returns a decision-ready, family-readable summary of one neighborhood, with a fit verdict, score bands, and editorial blurbs. It contrasts with a 'data dump', distinguishing from tools like 'get-neighborhood' or 'search-neighborhoods'.

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 'start here when a family wants an answer, not a data dump', providing clear when-to-use guidance. However, it does not explicitly mention when not to use or suggest specific sibling tools as alternatives, though the context of siblings is available.

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, which the description confirms with 'Get'. The description adds context by listing the specific resource types, which is not in annotations.

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

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

The description is a single, front-loaded sentence that communicates the core purpose and details efficiently, with no wasted words.

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

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

Given the presence of an output schema, good annotations, and a simple single-parameter tool, the description sufficiently covers what the tool does and returns. Minor gap: no error handling or validation context, but not critical.

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 basic description 'NTA code'. The tool description mentions 'neighborhood' but does not add new meaning beyond associating it with nta_code, 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 specifies the verb 'Get', the resource 'family resource counts', and the scope 'for a neighborhood', listing specific resource types. It distinguishes from sibling tools like get-schools or get-safety.

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 (when you need family resource counts) but provides no explicit guidance on when not to use or how it compares to alternatives like get-neighborhood or get-schools.

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 and idempotentHint=true, so the description doesn't need to restate safety. The description adds value by listing the specific indicators and mentioning the family-readable interpretation, but it doesn't disclose any additional behavioral traits beyond what annotations cover.

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 sentence that efficiently conveys the tool's purpose and returned data without wordiness. It could be slightly more structured (e.g., separating listed items), but overall it is well-paced for an AI agent to quickly 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 has one parameter and an output schema (not shown), the description reasonably covers what the tool returns. It misses guidance on usage context but is otherwise sufficient for a straightforward read-only query tool.

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

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

Schema coverage is 100% (the sole parameter nta_code has a description in the schema). The tool description adds no further explanation about what an NTA code is or its format, so it provides no added semantic value beyond the schema.

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

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

The description clearly states the tool retrieves safety and health indicators for a neighborhood, listing specific data types (crime, collisions, air quality, etc.) and noting the inclusion of interpretable scores. This distinguishes it from sibling tools like get-activities or get-neighborhood-summary, which serve different purposes.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, exclusions, or scenarios where another sibling tool would be more appropriate. The intended use is only implied by the name and content.

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

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

Description discloses that it returns quality ratings, grade levels, contact info, and response reports total/returned. Consistent with readOnly and idempotent hints; no contradictions.

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

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

Two concise sentences that efficiently convey purpose, included data, and parameter usage. No redundant information.

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

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

Given the tool's complexity (4 params, output schema exists), the description covers purpose, included data, pagination, and the count_only feature, sufficing for effective use.

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

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

Schema coverage is 100%, description adds usage context for count_only and pagination, plus notes about response reporting, which enhances understanding beyond schema descriptions.

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

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

Specific verb 'Get' with resource 'schools within a neighborhood', clearly listing types (public, charter, private) and what's included (ratings, grades, contact). Distinct from sibling tools like get-neighborhood.

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 guidance on using count_only for quick summary and limit/offset for paging. Does not explicitly discuss when not to use, but the 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 already declare the tool as read-only and idempotent. The description adds value by confirming the sort is deterministic and explaining that weights override priorities when both are given, providing behavioral context beyond annotations.

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

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

The description is concise (two sentences), front-loaded with the primary purpose, and covers inputs, output, and an important behavioral note (deterministic, not the Smart Match). No unnecessary words.

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

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

Given the presence of an output schema (not shown but noted), the description covers all key aspects: what the tool does, inputs, output structure, and behavioral nuances. For a parameter count of 5 with 100% schema coverage, the description is complete and 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the relationship between weights and priorities, the internal normalization of weights, and the role of min_population as a residential floor, which goes beyond schema descriptions.

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

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

The description uses a specific verb-resource combination ('Rank NYC neighborhoods'), lists the metrics involved, and distinguishes from sibling tools by mentioning 'deterministic weighted sort' and referencing the Motley app's Smart Match.

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 clearly states when to use this tool (ranking by family priorities) and mentions optional borough scoping. It does not explicitly enumerate alternatives, but the context of sibling tool names (e.g., 'compare-neighborhoods', 'search-neighborhoods') implies differentiation.

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 known to be safe and idempotent. The description adds value by specifying the exact fields returned (NTA codes, names, boroughs, centroid coordinates), which is not in the annotations. No contradictions are present, and the description aligns with the read-only 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 concise: two sentences that efficiently convey the purpose and output. No unnecessary words, and the structure is front-loaded with the action ('Search and filter') followed by the result. Every sentence is informative.

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 (3 optional params, no required params, and an output schema), the description is complete. It states the tool's scope (NYC neighborhoods), filters, and return fields. The output schema presumably provides the structure, so the description need not elaborate further. All relevant aspects are covered.

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 having a clear description (e.g., 'Search NTA name (case-insensitive)' for query, 'Filter by borough' with enum). The tool description mentions filtering 'by borough or name' but does not add additional detail beyond what the schema provides. With full coverage, a 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's function: searching and filtering NYC neighborhoods by borough or name. It specifies the output fields (NTA codes, names, boroughs, coordinates), and the name 'search-neighborhoods' combined with the description distinguishes it from sibling tools like 'find-neighborhood' (likely single result) or 'get-neighborhood' (by ID). This is a specific verb+resource combination.

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 usage for broad search and filtering but does not explicitly state when to use this tool versus alternatives like 'find-neighborhood' or 'get-neighborhood'. There is no guidance on when not to use it or what scenarios are better suited for other tools. The presence of optional params suggests flexibility, but explicit exclusions are missing.

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