My Noticeboard

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

Annotations already declare a read-only, closed-world operation, and the description adds real value beyond them: it discloses that results are a curated 'best of' selection spanning three geographic tiers and formatted as a printable sheet. It stops short of saying whether items are links, whether results are paginated, or what happens when a topic yields no matches.

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 tight sentence with no waste, front-loading what the agent receives. It is a noun phrase rather than a full statement, which slightly weakens the lead but keeps it efficient.

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 only two parameters, one required, full schema coverage and no output schema, the description covers the essentials: what the sheet contains and how it is scoped geographically. Missing only failure behavior and return shape, which is minor for this 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%, so both parameters and their constraints are fully documented in the schema. The description reinforces the topic dimension but says nothing about the 'near' parameter that drives the local section, so it adds no meaning beyond the structured fields.

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 concrete artifact (a curated sheet of services and resources for one topic) and its scope (local, area-wide and national tiers). It is clear what the tool produces, but it never explicitly distinguishes itself from search_services or get_service, so an agent must infer the curated/packaged nature on its own.

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 phrases "ready-made" and "as a link worker would print" imply this is the packaged alternative to searching manually, but no when-to-use condition or named alternative is stated. An agent can guess the intent but gets no explicit routing rule against siblings like search_services.

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 openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the returned field set (contacts, opening times, address, last-checked date), which matters since there is no output schema. It says nothing about not-found behavior or data freshness semantics beyond the 'last checked' field name.

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?

One sentence, front-loaded with the verb and resource, then the returned fields enumerated compactly with no filler. Appropriately sized for a single-parameter read 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?

Because there's no output schema, the description carries the burden of describing return content, and it does so by listing the field categories. What remains missing is minor: no guidance on unknown ids or on whether the response is a raw record versus a composed view.

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 a single parameter at 100% schema coverage, the schema already explains that id is the service id or slug from search_services. The description adds no meaning beyond that, so 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 and resource ('Full details for one service') and enumerates the payload fields, so an agent knows exactly what it retrieves. It doesn't name a sibling to distinguish itself from, though the 'one service' framing implicitly contrasts with search_services.

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: the description says 'one service' while the schema notes the id comes from search_services, so the agent can infer this is the follow-up lookup to a search. There is no explicit when-to-use/when-not statement, no mention of what happens if the id is unknown, and no comparison to get_resource_sheet or get_whats_on.

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, closed world). The description adds one genuinely non-obvious behavior — cancelled dates are included and flagged rather than filtered out — which matters for interpreting results. It says nothing about ordering, how many results come back by default, or what the response records contain, so the disclosure is useful but thin.

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 short sentences, front-loaded with the resource definition before the query-style examples and the cancellation caveat. Little waste, though the two example questions could arguably be one.

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 carries some burden for describing what comes back; it partially meets this by telling the agent that cancelled sessions appear and are marked. Gaps remain around result count/default limit behavior and the fact that all five parameters are optional, but the essentials for calling it correctly are present.

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 60%, so the description should compensate for the undocumented remainder; it does not. It re-states the `question` parameter with illustrative examples (modest added value, since the schema already says 'plain-English question' and that other fields override it) and ignores `when`'s enum, `limit` bounds, and `near`'s accepted formats.

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 the resource ('sessions and activities') and the two axes it operates on ('a time and place'), which is a specific retrieval purpose. It does not explicitly contrast itself with the nearest sibling, search_services, so an agent must infer whether 'what's on' and 'search services' overlap.

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 two example questions imply the intended use for natural-language event queries, but the description never says when to prefer this over search_services or get_service, nor what conditions make it the wrong choice. Usage is inferable rather than 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=true and openWorldHint=false, so the safety and closed-vocabulary profile is covered. The description adds that the taxonomy is hierarchical (needs nested under themes), but says nothing about whether the set is static or how large it is, which matters for an agent deciding to dump the whole list.

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 no filler; the definition of the resource comes first and the integration hint second, so the agent can stop reading as soon as it knows what it needs.

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 parameters and no output schema, the description carries the full burden of describing the return value, and it only hints at it (codes plus a themes/needs hierarchy) without saying what fields each topic carries. For a zero-argument enumeration tool this is workable but leaves the agent guessing at the response shape.

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 and there is nothing for the description to compensate for. It still implies the return contains 'codes', which is the field an agent needs.

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 the resource concretely ('the topics (themes and the needs under them) used to tag listings'), which is specific enough that an agent knows it returns a taxonomy rather than listings themselves. It does not use an explicit verb like 'list all', but the hierarchy (themes with needs beneath) and the tag-listing scope distinguish it from every sibling.

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

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

The second sentence explicitly routes the agent: the returned codes are the value to pass as the topic for get_resource_sheet, so the description states the downstream use rather than leaving it to inference. It gives no when-not guidance or alternative sources, so it stops short of a 5.

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

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

Annotations already establish that this is a read-only, closed-world operation. The description adds useful behavioral context by stating that results are ranked and include distance and freshness information ('when each was last checked'), which goes beyond the annotations and helps set expectations.

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 with zero waste, and the core purpose is front-loaded before the return-value detail. Every sentence adds useful 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?

For a simple search tool with annotations and no output schema, the description is largely complete: it explains the search scope, ranking, distance, and freshness. The main remaining gap is the undocumented limit parameter, but the schema constrains it numerically.

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 75%, with query, near, and radius documented but limit left undocumented. The description reinforces the need/place concepts but adds no detail about limit behavior, pagination, or default result size beyond what the schema partially 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 verb (find/search) and the resource scope: community groups, charities, and support services, filtered by need and place. It is clearer than a generic search tool, but it does not explicitly distinguish itself from sibling get_service, which likely retrieves a single service.

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 phrase 'by need and place' implies the search criteria and gives some context for when to use the tool. However, it does not state when to choose it over siblings such as get_service or list_categories, nor does it include exclusions or prerequisites.

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?

Adds real context beyond the annotations: "We read the page ourselves; nothing is published on your word" discloses the human-curation workflow, "Needs an API key" discloses an auth prerequisite the annotations don't carry, and the receipt/idempotency sentence explains what the idempotentHint actually yields. No rate limits or failure behavior, which keeps it below 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?

Four short sentences, front-loaded with what to submit and followed by eligibility, review behavior, auth, and return semantics. No filler; every sentence contributes a distinct fact.

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 non-destructive submission tool with full schema coverage and no output schema, it covers eligibility, auth, the review step, and what the receipt means. Only the absence of any failure/validation behavior (e.g. what happens for an already-suggested URL) leaves a small 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 description coverage is 100%, so all four parameters are already documented, including the idempotency_key retry semantics. The description's mention of "address of a group's own website ... or an iCal feed" loosely maps to url but adds no format or constraint detail beyond the schema, 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 concrete verb ("Tell My Noticeboard") and resource (a URL or iCal feed of community activity), with examples of acceptable sources (group website, parish, library, venue programme). It doesn't name any sibling tool, so the differentiation from readers like search_services or get_whats_on is implied by the submission framing rather than stated.

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

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

Gives clear eligibility criteria — "Community-led and voluntary activity only" — and enumerates acceptable source types, which tells the agent when the tool applies and implicitly when it doesn't. It never explicitly routes to or excludes a named sibling, so the guidance stops short of full alternative-selection coverage.

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