CityAlert

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds genuinely non-structured context: the returned token grants write access via PUT /api/dashboards and must be saved — a security-relevant trait absent from the annotations and schema.

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

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

Two sentences, front-loaded with the core action followed by the critical return-value caveat. Every clause earns its place, with no padding or restatement of the title.

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

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

An output schema exists, so the description is not obligated to explain return values, yet it helpfully clarifies the token's privilege. Annotations carry the safety profile. The remaining gap is that the 'name' parameter and dashboard-sharing behavior are left opaque.

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 only 50% (the 'name' parameter has no description and only a maxLength constraint), yet the description says nothing about the meaning, format, or constraints of name or config. It does not compensate for the coverage gap, so it adds no parameter 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 a specific verb and resource ('Create a shareable dashboard'), so an agent immediately knows what the tool produces. It does not explicitly name the sibling get_dashboard or contrast read vs. create, so it is clear but not sibling-differentiating.

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 by 'Create a shareable dashboard' — an agent can infer this is the write counterpart to get_dashboard. However, there is no explicit when-to-use/when-not statement, no prerequisites, and no named alternative for retrieving or updating an existing dashboard.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the geographic and temporal coverage limits, which is useful but modest; no mention of response size or ranking methodology.

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 short sentences, front-loaded with the data content and followed by the scope constraint. No filler or redundant restatement of the title.

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 rich annotations, the description does not need to explain return values, and the params are schema-documented. The only gap is the lack of differentiation from sibling read tools, which an agent choosing between get_crime_year, get_incidents, and get_trends would benefit from.

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% for both parameters (year range and includeIncidents cost warning), so the schema carries the semantics. The description adds nothing parameter-specific beyond restating the 2003-present range already in the schema, making the baseline 3 correct.

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

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

States a specific verb-resource pairing (full-year VPD crime data) plus the shape of what comes back (totals and ranked neighbourhood stats), which is more than a restatement of the name. It does not, however, explicitly distinguish itself from close siblings like get_incidents or get_trends, so the agent must infer the boundary.

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?

'Vancouver only, 2003-present' gives a scope constraint but no when-to-use versus get_incidents (which covers incident points) or get_trends. The usage context is implied by 'full-year' rather than stated as an explicit routing rule.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the mild qualifier 'shareable', which is useful context but largely restates what the annotations already guarantee.

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?

A single short sentence, front-loaded with the verb and resource, with no filler. The parenthetical is slightly redundant against the readOnlyHint annotation but costs little.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety semantics. The description is thin but sufficient for a one-parameter id lookup; it stops short of telling the agent how to obtain a valid id.

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 0%, but there is only one trivially-named parameter (id). The phrase 'by id' confirms the id identifies a saved dashboard but adds no format or sourcing detail (e.g., where the id comes from). Minimal value over the bare 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 (Read) and resource (a saved dashboard) plus the retrieval key (by id), so an agent can distinguish it from create_dashboard and the other list/get siblings. It is clear, though it doesn't explicitly name a sibling to route away from.

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 only implied: 'by id' tells the agent it needs a known identifier, but there is no statement of when to prefer this over alternatives such as listing or creating, nor any prerequisite guidance. Adequate but leaves the routing decision to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds genuinely new behavior: results come from a shared ~15-minute snapshot rather than live data, and real-time refresh requires an entitlement. That staleness/caching disclosure is exactly the kind of context an agent needs and is not in the annotations. It omits pagination/ordering behavior.

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 tight sentences: identity/scope first, filter surface second, behavioral caveat last. No filler, and the most decision-relevant constraint (snapshot staleness) is stated before the pointer to developer docs.

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 10 optional params, full schema coverage, rich annotations, and an output schema, the description carries the necessary extra context: merged provenance and snapshot freshness. Only minor gaps remain (ordering, default/max limit behavior, dedup across feeds), which the output schema and param defaults largely cover.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including bbox format, detail modes, and the refresh entitlement caveat. The description's filter list and entitlement note largely restate what the schema says. 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 names the resource (live incidents) and adds meaningful scope beyond the tool name: merged from all feeds plus manual reports. That scope distinguishes it from get_news and get_crime_year, though it never explicitly names those siblings. Clear verb+resource with implicit differentiation.

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

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

It lists the filter dimensions (region, category, group, severity, source, bbox), which implies the intended use case is filtered incident retrieval, and it flags the ~15-minute snapshot / refresh-entitlement constraint. However, it never states when to choose this over get_news, get_crime_year, or get_trends, and gives no 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, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered without the description. The description adds the region-vs-ad-hoc duality, but omits the caching behavior that the schema's refresh parameter alludes to, which is meaningful context for a news tool.

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?

A single front-loaded sentence with no filler, so nothing needs trimming. It is efficient, though almost too terse for a tool with a cache-bypass parameter to explain.

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?

Output schema exists, so return values need not be described, and annotations cover the safety profile. What is missing is that place is optional (region defaults) and what the news source/recency characteristics are, which matters for a news 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 description coverage is 100%, so both parameters are already documented in the schema, establishing a baseline of 3. The description's mention of an 'arbitrary place name' loosely maps to the place parameter but adds no format, limit, or semantics beyond it, and never addresses refresh.

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 resource (safety news) and its two retrieval modes: per-region, or by arbitrary place name. That is enough to separate it from read-only siblings like get_incidents and get_trends, though it never explicitly states what distinguishes it from those tools.

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

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

It implies two invocation modes but gives no guidance on when to choose news over incidents/trends/crime_year, and no preconditions. The 'or' construction is descriptive rather than prescriptive, leaving the agent to infer selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds real behavioral context beyond that: which underlying datasets are aggregated and the depth of each history window (6y/10y/3y), which tells the agent how far back answers can reach. It does not mention pagination or response size limits, keeping it short of a 5.

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, each earning its place: scope first, usage second, routing to the alternative last. No filler, no restatement of the tool name, and the most decision-relevant content (what data and how far back) 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?

An output schema exists, so return-value documentation is not the description's burden. Given the zero-parameter surface and full annotation coverage, the description supplies everything needed to decide when this tool answers the question and when get_incidents or get_crime_year should be preferred.

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 takes zero parameters, so per the rubric the baseline is 4. The description still communicates the implicit result dimensions (year, month, type, region) that shape what the agent can ask for, even though no argument surface exists.

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?

Names a specific resource (historical aggregates) and enumerates the exact datasets with their temporal windows: VPD crime by year/month/type, USGS M4+ quakes, GDACS events, plus report and live snapshot stats. It also explicitly carves itself away from get_incidents, so an agent can distinguish it from 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?

States the selection condition directly ('Use for questions about patterns over time — crime trends, quake frequency, disaster cadence') and names the alternative tool plus the condition that routes there ('For what's happening right now, use get_incidents'). Both when-to-use and when-not-to-use are explicit.

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 fully covered by structured data. The description adds the cross-reference to get_incidents and lists return fields, but those fields are also captured by the output schema, so little behavioral context is added 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 compact sentences with zero waste; the resource and return shape are front-loaded and the usage hint follows immediately. Nothing extraneous.

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 explain return values, yet it summarizes them helpfully. Combined with the get_incidents linkage, an agent has everything needed to call it, though a note on result size or pagination would complete the picture.

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 takes zero parameters, so the baseline is 4. Nothing in the description needs to explain argument semantics, and it correctly implies a no-argument, full-list call.

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 ('List') and resource ('CityAlert focus regions') and even enumerates the returned fields (key, label, center, zoom, bbox), so the agent knows exactly what comes back. It links to get_incidents, giving partial sibling differentiation, though it does not contrast with other list-style 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?

Explicitly states the follow-on use case: 'Use region keys with get_incidents,' which tells the agent why and when to call this tool. There is no when-not guidance or mention of alternatives, but the practical trigger 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 cover the write/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial non-structured context: moderation before public appearance, the 'report submission disabled' blocked-caller error, and the 20 reports/hour MCP rate limit. This is exactly the kind of extra behavioral disclosure wanted.

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 tight, front-loaded clauses with no filler. Slightly dense but 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?

An output schema exists so return values need not be explained, and the behavioral notes cover moderation and failure modes. Only missing piece is explicit sibling differentiation/usage guidance.

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 bounds, enums, and defaults fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the 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?

States a specific verb (file/submit) and resource (manual geolocated incident report), and parenthetically ties it to the POST /api/reports endpoint. It does not explicitly distinguish itself from sibling read tools like get_incidents, though the write framing is clear.

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

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

Implied usage (file an incident report) but no explicit when-to-use vs alternatives or when-not-to-use conditions. The moderation and error notes give context but not selection guidance.

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