Motley MCP Server

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds important behavioral context beyond that: 'at least one is required, and an invented one returns nothing', 'Program focus is tagged on public and charter schools only', and admission methods match if the school admits by ANY listed method. These are non-obvious call semantics not inferable from annotations alone, so the description significantly enhances transparency. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place, covering purpose, usage alternatives, required filters, parameter semantics, and a critical scoping caveat. It is front-loaded with the core action and enumerates filters in a logical flow. No filler or repetition of what the schema already says verbatim, so it is appropriately sized for the tool's complexity.

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

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

For a tool with 8 parameters, no required schema fields, and many sibling lookup tools, the description is remarkably complete. It explains when to use it vs. get-schools, what filter is required (at least one), how to avoid invalid inputs, semantics of each filter group, and even points to related tools for admissions method explanations. The presence of an output schema means return format need not be described, and the description covers all other relevant context.

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

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

Even though schema description coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies that 'borough is NOT a district' and 'never guess one' for district, explains the grade_band values (prek, elementary, middle, high) with examples, and notes that 'program_categories' covers 'extracurricular' as clubs and applies only to public/charter schools. This goes far beyond the raw schema and tells the agent exactly how to interpret and combine parameters.

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: 'Find NYC schools citywide by what a family wants' and lists exactly what filter dimensions are supported. It explicitly distinguishes itself from sibling tool get-schools by specifying that browse-schools is for family-describes-kind scenarios while get-schools is for already-known nta_code neighborhood queries, fully differentiating it from siblings.

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

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

The description gives explicit when-to-use guidance: 'Use this when the family describes the KIND of school they want; use get-schools when you already have an nta_code...' It also provides strong behavioral rules like 'Pass only the filters actually stated', 'at least one is required, and an invented one returns nothing', and warns against guessing districts, giving clear operational guardrails for when and how to invoke the 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. The description adds behavioral context about the output structure (per-metric matrix with bands and leader), which goes beyond annotations. 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 a single well-structured sentence that front-loads the main action and includes essential details. Every part is informative with no redundancy or fluff.

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

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

Given the presence of an output schema (not shown but indicated) and rich annotations, the description is complete. It covers input, output, and metrics, and references the source of NTA codes. No gaps for a comparison 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?

The input schema has 100% coverage for the single parameter 'nta_codes', with a detailed description including constraints (2-6, from search-neighborhoods, unscored codes dropped). The tool description only mentions passing an array, adding no new meaning beyond the schema. Baseline score 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 compares 2-6 NYC neighborhoods across 9 specific metrics, with explicit input (NTA codes) and output (per-metric matrix with leader). It distinguishes itself from siblings like 'rank-neighborhoods' by focusing on side-by-side comparison rather than ranking.

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

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

The description provides clear context for when to use the tool (to compare neighborhoods side by side), but does not explicitly mention alternatives or when not to use it. This level of guidance is sufficient for a well-defined tool without conflicting 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?

The description notes the tool is an explainer with no side effects, consistent with readOnlyHint and idempotentHint annotations. It adds context about returned content but does not cover additional behavioral aspects like dependencies or potential errors.

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

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

The description is well-structured, front-loading the main purpose and then listing specifics. It is somewhat lengthy but necessary to enumerate all valid methods and their details. Each sentence contributes to clarity.

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

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

Given the complexity of NYC admissions, the description covers the key outputs (explainer, deadline, requirements, paperwork). With an output schema present, this is sufficient contextual completeness.

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

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

The schema already describes the single parameter with all valid values (100% coverage). The description adds meaning by explaining what each method entry entails, providing semantic value beyond the schema's list.

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 explains an NYC admission method in full, including plain-English explainer, deadline, requirements, and paperwork. It distinguishes from siblings like get-admissions-methods by emphasizing detailed explanation.

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 lists valid input values (method keys and early entry points), guiding correct invocation. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds that geocoding uses OpenStreetMap and is NYC-bounded, and details the output fields. It does not mention potential errors (e.g., ambiguous addresses, out-of-bounds coordinates) or rate limits, but overall adds useful 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?

Three sentences efficiently convey purpose, inputs, outputs, and usage guidance. No redundant information. Front-loaded with the core action.

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 does not need to detail return values. It covers inputs, output summary, and usage context. Lacks explanation of validation (lat/lng bounds) or error handling, but is sufficiently complete for a geocoding tool with good schema coverage 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 baseline is 3. The description reinforces that lat/lng are for coordinates and address for strings, and specifies the geocoding source (OSM). It adds minimal additional meaning beyond the schema, which already describes the parameters thoroughly.

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: converting a NYC address or coordinates into an NTA neighborhood. It specifies inputs (address or lat+lng) and outputs (NTA code, name, borough, summary). It distinguishes itself from siblings like search-neighborhoods by focusing on direct geocoding and identifier retrieval.

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

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

The description explicitly advises using this tool to transform a real-world location into a neighborhood for other tools. It clearly states the two input options. However, it does not explicitly exclude cases where search-neighborhoods or get-neighborhood might be preferred, and lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds operational context: data source (Foursquare), pagination behavior, count_only mode, and last_refreshed meaning. 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?

Three concise sentences: purpose, usage modes, and a data freshness note. Every sentence adds unique value with no redundancy or fluff.

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

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

Given output schema exists and annotations cover safety, the description sufficiently covers purpose, source, paging, count_only mode, and data freshness. Agent has enough to use tool correctly.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reinforces the schema but adds only moderate extra context (e.g., 'for category breakdown', 'reports total/returned'). 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 clearly states the tool retrieves kids' activities and businesses in a neighborhood, listing example categories and data source (Foursquare). It distinguishes itself from sibling tools like 'get-schools' or 'get-safety' by focusing on activities.

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 explains when to use the tool and provides explicit guidance on using count_only for category breakdown and limit/offset for paging. However, it does not explicitly state when NOT to use or mention alternatives among siblings.

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

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

The description adds value beyond annotations by specifying the data source and limitations of data availability. Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, which the description does not contradict.

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, well-structured paragraph that front-loads the purpose, lists outputs, provides usage guidance, and notes limitations. Every sentence adds essential information 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?

Given the tool's simplicity (one parameter, clear purpose, good annotations, and presence of an output schema), the description sufficiently covers all aspects: what it does, what inputs are needed, what outputs to expect, and when data may be absent.

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 with examples and constraints. The description reinforces the meaning of 'dbn' and directs users to get-schools for valid values, adding context 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's function: retrieving admissions competitiveness for a school, including specific metrics like seats, applicants, applicants-per-seat, offer/fill rate, and a tier. It explicitly distinguishes from sibling tools by focusing on demand data for a single school.

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 instructs to pass a school DBN from get-schools, and notes the data source (MySchools) and scope (mostly screened/choice high schools; others usually have none). This implicitly guides when to use and when to expect empty results, though explicit alternatives to siblings are 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 already declare readOnlyHint and idempotentHint. The description adds context about live program counts, special_badge, and filter effects, going beyond the annotations.

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

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

The description is a single long sentence that is information-dense but could be more structured for readability. It front-loads the purpose well but packs many 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 presence of an output schema, the description adequately explains the scope, key fields (program count, special_badge), and filters. It is comprehensive for a reference 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% with descriptions for both parameters. The description adds value by explaining that filters narrow the count and mentioning the effect of 'band' and 'governance'.

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 the full NYC school-admissions reference with specific entry points and methods. However, it does not explicitly differentiate 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 implies it is a reference tool ('Knowledge only') but does not explicitly state when to use it versus alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe and idempotent. Description adds that it returns similarity scores, which is 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?

Description is a single sentence with essential information: purpose, basis (9-dimension vector), and return value. No fluff, 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?

With an output schema present, the description need not detail return structure. It mentions similarity scores. Could briefly note dependency on neighborhood data availability, but overall complete for the tool's simplicity.

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

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

Schema description coverage is 100%, and the schema has clear descriptions for both parameters (nta_code and limit). The description does not add extra meaning beyond what the schema already provides.

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 states the tool finds neighborhoods most similar to a given one, using a 9-dimension score vector. It lists example dimensions (family density, wealth, etc.) and distinguishes from sibling tools like compare-neighborhoods (compares two) and rank-neighborhoods (ranks 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?

Usage is implied: when you want similar neighborhoods based on the vector. However, no explicit guidance on when to use this versus alternatives like compare-neighborhoods or search-neighborhoods, nor any exclusions mentioned.

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 is not required to restate those. It adds value by mentioning cached editorial blurbs, but does not detail return format or error behavior. 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?

Two sentences, front-loaded with the main purpose, no redundant words. Every phrase adds value.

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 output schema present and a single required parameter, the description covers key aspects. Could optionally mention read-only nature (courtesy), but annotations handle that.

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

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

The schema already describes nta_code fully (100% coverage). The description adds context by linking to search-neighborhoods for obtaining the code, enhancing 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 specifies the action (Get full details), resource (single NYC neighborhood), and scope (demographics, scores, location, interpretation). It also references the source of the required parameter (nta_code from search-neighborhoods), clearly distinguishing it from siblings like get-neighborhood-summary.

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 the nta_code from search-neighborhoods, providing a clear prerequisite. Does not explicitly state when NOT to use it, but context implies it for detailed data vs. summary.

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. The description adds behavioral context by detailing the output format (one-paragraph verdict, labeled score bands, cached editorial blurbs) and noting that raw scores are still available. It does not contradict annotations.

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

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

The description is two sentences long, front-loading the purpose with the first sentence. Every word adds value; there is no fluff. The structure efficiently conveys what the tool does and when to use it.

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 a single required parameter, has an output schema (mentioned in context), and annotations cover safety/idempotency, the description provides sufficient contextual completeness by describing the output content. It does not cover error handling or prerequisites, but for a simple lookup tool this is adequate.

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

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

The input schema has 100% description coverage for the single parameter nta_code (example provided). The description does not add any additional meaning or constraints beyond what the schema already provides, so baseline score of 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 clearly states the verb 'Get', specifies the resource 'a decision-ready, family-readable summary of one NYC neighborhood', and gives concrete examples of content (fit verdict, score bands, editorial blurbs). It also distinguishes from siblings by positioning it as 'the interpretation-first front door' vs. a data dump, differentiating from 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?

The description explicitly says 'start here when a family wants an answer, not a data dump', providing clear when-to-use guidance. It implies alternatives (raw data tools) but does not name specific sibling tools explicitly.

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

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

Annotations declare readOnlyHint and idempotentHint, which align with the 'Get' verb. The description adds context on the specific resource types counted, providing behavioral detail beyond the minimal annotation hints.

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

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

Single sentence front-loads the primary action and lists examples. No redundant or filler wording. Title is null but description is efficiently 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 output schema exists and only one parameter is required, the description sufficiently sets expectations. It lists resource types and the scope (neighborhood). Minor gap: does not clarify if counts are integers or include metadata, but output schema likely covers this.

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

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

Schema coverage is 100% with a single parameter nta_code described as 'NTA code'. The description mentions 'neighborhood' but does not clarify what NTA code is or how to find it. Baseline 3 is appropriate as the schema already documents the parameter.

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 family resource counts for a neighborhood, listing specific resource types (recreation centers, playgrounds, etc.). It distinguishes from sibling tools like get-neighborhood-summary by focusing exclusively on resource counts.

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?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, limitations, or conditional scenarios like when to prefer compare-neighborhoods or get-neighborhood-summary.

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, indicating safe read-only behavior. The description adds value by specifying that the output includes a 'family-readable interpretation' of scores, beyond the raw data. It does not contradict annotations.

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

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

The description is a single concise sentence that front-loads the tool's purpose and lists key indicators efficiently. Every phrase earns its place, with 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 one parameter, strong annotations, and an output schema (implied by description), the description adequately covers what the tool does and returns. No missing information would prevent correct selection or 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?

With 100% schema coverage and a single parameter ('nta_code'), the description adds meaning by linking the parameter to the tool's output (indicators for a neighborhood). It could elaborate on the format or source of NTA codes, but the connection is clear.

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 lists multiple specific indicators (crime, collisions, HPD violations, etc.) and mentions an interpretation of scores, making it clear what the tool provides. It distinguishes from sibling tools like 'get-neighborhood' and 'get-neighborhood-summary' by focusing on safety and health.

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 the tool should be used for safety and health indicators, but does not explicitly state when to use it versus alternatives (e.g., 'get-neighborhood-summary'). No exclusions or comparisons are provided, leaving the agent to infer context from the sibling list.

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 adds context beyond annotations: mentions included fields (quality ratings, grade levels, contact info) and pagination behavior (response reports total/returned). Annotations already indicate read-only and idempotent, and description is consistent.

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: first defines purpose, second gives usage guidance. No wasted words. Front-loaded with essential 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?

Description covers the tool's purpose, parameter usage, and output characteristics (fields included, pagination). Output schema exists, so return format is not needed. Suitable for a read-only school listing 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%, baseline 3. Description adds value by explaining the use case for count_only vs limit/offset, and notes that limit is ignored when count_only. Clarifies the interaction between parameters.

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 'Get', the resource 'schools', and the scope 'within a neighborhood', and specifies types (public, charter, private). It distinguishes itself from sibling tools (e.g., get-neighborhood, get-safety) by focusing on schools.

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 guidance on using count_only for a quick summary and limit/offset for pagination. Lacks explicit exclusion of alternatives, but sibling tools are sufficiently different in purpose.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description reinforces that the tool is a deterministic weighted sort and notes what it does not include ('the per-child Smart Match stays in the Motley app'). No contradictions, and behavioral traits are well disclosed.

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 efficient sentences: the first introduces the core action and inputs, the second details output and a behavior note. No fluff; every sentence contributes meaning.

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

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

Given the tool's complexity (5 parameters including nested objects, output schema exists), the description covers all necessary aspects: inputs, output (fit score with breakdown), parameter interaction, and a clarifying note about determinism. The provided contextual signals (high schema coverage) mean the description adds complementary detail.

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 significant value: it explains the relationship between 'weights' and 'priorities' (weight override, rank decay mapping), and clarifies the 'min_population' parameter's purpose (excludes non-residential areas). This goes beyond what the schema provides.

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: ranking NYC neighborhoods based on family priorities using weights or keywords. It distinguishes from sibling tools like 'search-neighborhoods' or 'find-neighborhood' by emphasizing the ranking and weighted scoring 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 specifies how to use the tool: provide per-metric weights and/or ranked keywords, optionally scope to a borough. While it doesn't explicitly state when not to use it or name alternatives, the context is clear and the deterministic sort hint guides appropriate 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 safety is clear. Description adds return field details but no further behavioral traits like pagination or rate limits.

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

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

Single sentence front-loading purpose and output. No filler, every word contributes.

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?

Tool has 3 optional params and an output schema; description covers search/filter semantics and return fields. Slight gap: no mention of limit's role, but schema covers it.

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

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

Schema coverage is 100%, so parameters are documented. Description restates the role of query and borough but adds no new 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?

Description clearly states verb 'search and filter', resource 'NYC neighborhoods', criteria 'by borough or name', and return fields. Distinguishes from siblings like find-neighborhood and get-neighborhood by emphasizing filtering.

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?

No guidance on when to use this tool versus alternatives like get-neighborhood or compare-neighborhoods. Does not mention prerequisites or exclusions.

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