Navigi: community services across Canada

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: every row carries the public page URL and the date the listing's own site was last checked, plus a citation obligation — useful since there is no output schema.

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

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

Two tight sentences: scope first, then the data-quality/citation contract. No filler and nothing repeated from structured fields.

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 no output schema, the description usefully states what each returned row contains (URL, last-checked date, citation requirement). An agent still lacks detail on pagination/limit behavior and result ordering, but the core call path is complete.

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 83%, so the schema largely documents the parameters, setting a baseline of 3. The description reinforces the 'need' vocabulary with examples and notes there are 18 more needs, but adds no format or semantics beyond what the schema already states.

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 (Find) + resource (community and social services) + geographic scope (a Canadian community on navigi.ca), with concrete examples of needs. It does not name or contrast with the sibling tools (services_near, list_needs), so an agent must infer which of the overlapping lookups to pick from scope alone.

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 the enumerated need categories and the required place/province pairing, and there is a post-call instruction to cite the URL and checked date. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as services_near or list_needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds useful return-content context—listing counts by category and the community page URL—but does not discuss pagination, formatting, or permissions.

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 with no wasted clauses. It is concise and readable, though its terseness leaves the agent without usage 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?

The tool is low complexity with only two parameters and rich annotations, and the description does explain the main returned data. However, with no output schema and weak parameter coverage, the description should say more about the province input and the shape or limits of the returned counts.

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 community parameter notes 'slug or name,' but province is undocumented. The description does not compensate by explaining province format or how community identifiers should be supplied, adding no parameter semantics 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 identifies the resource and content returned: one community's listing counts by category and its page URL. It is more specific than the title alone, though it does not explicitly contrast the tool with its siblings find_services, list_needs, or services_near.

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 when-to-use guidance is provided. The description does not mention alternatives, prerequisites, or exclusions, so an agent must infer that this tool is for community overview data rather than service or needs searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and no destructiveness, so the safety profile is fully covered. The description adds real value by disclosing the shape of the content returned (categories plus their associated searcher terms), which is behavior no annotation conveys. With no output schema, however, it says nothing about result size, ordering, or format, so the disclosure stops short of full transparency.

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 with zero filler. The payload content is stated first and the routing advice follows, which is the correct front-loading for a zero-argument lookup tool.

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

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

For a no-parameter, closed-world listing tool with rich annotations and no output schema, the description covers what it returns and when to call it. The remaining gap is scale and format of the returned list, which an agent would want for planning, but that is a minor omission rather than a blocking one.

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 there is nothing for the description to disambiguate; the baseline of 4 applies. Schema coverage is reported at 100% and the empty object confirms no inputs are expected.

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 resource — the service categories navigi.ca uses — and adds that each carries the searcher terms it answers, which goes beyond the bare title. The only friction is terminological: the name says "needs" while the description says "service categories," so an agent must infer these are the same concept. Still clearly distinguishable from the sibling tools, which operate on services and communities rather than the category vocabulary.

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?

"Call this first when unsure which need word to use" is an explicit sequencing instruction that tells the agent when this tool precedes others. It implicitly routes the agent to find_services once the term is known, but never names that sibling or states when this tool should be skipped.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds no further behavioral detail — no mention of result ordering, pagination, what a "need" match means, or whether radius is in km — so it does not go beyond the structured metadata.

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 capability and followed by the routing rule — no filler. Minor cost: "optionally for one need" is terse enough to be slightly ambiguous about whether need affects ranking or filtering.

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?

No output schema exists and the description gives no return-shape hint (list of services? distance field? capped by limit?), which matters for a search tool. Combined with five undocumented parameters, an agent knows roughly when to call it but not what to expect back.

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 0% schema description coverage, the description must carry parameter meaning; it does partially by mapping "radius" to km, "point" to lat/lng, and "optionally for one need" to need. It says nothing about limit, the km default of 25, the limit cap of 100, or units for coordinates, leaving real gaps for the two non-obvious 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?

Names a concrete resource (community and social services) and the scoping mechanism (radius around a point, optional need filter). An agent can tell it is the geo-proximity search variant, though the differentiation from find_services is only implied rather than stated by name.

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?

"Use when the person gives a location rather than a community name" gives an explicit selection condition that implicitly routes to find_services when a community name is available. No explicit when-not or edge cases (e.g., what to do with an address vs. coordinates), but the core routing signal is present.

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