BJJ and grappling gyms worldwide, plus upcoming competitions. Free, read-only.
Scored across 4 tools
Each tool covers a distinct entity and action: competitions search, gym search, single-gym detail by slug, and coverage/places listing. The find_gyms vs get_gym pair is explicitly linked in the descriptions (get_gym takes the slug returned by find_gyms), so the search/detail boundary is unambiguous.
All four names follow a consistent snake_case verb_noun pattern (find_competitions, find_gyms, get_gym, list_places). The verbs are used conventionally — find for search, get for retrieval by identifier, list for enumeration.
Four tools is lean but each maps to a real, non-overlapping need for a read-only directory (search gyms, search competitions, gym detail, coverage check). It is slightly thin — no tool for competition detail or name-based lookup — but nothing is redundant.
The read-only directory surface is well covered: gyms, competitions, gym details, and a coverage check. Minor gaps exist (no competition detail endpoint, no lookup by gym name, fixed caps with no pagination), but the descriptions give workarounds such as narrowing the area, so agents can operate.
Upcoming BJJ and grappling competitions from an aggregated public calendar: BJJ Square collects the dates organizers publish on their own public listings (IBJJF, AJP, Smoothcomp, national federations and others). Search by country and date range. Returns at most 10 per call, each with the official organizer page (the source to register and to confirm details), plus the BJJ Square calendar page for the full list.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date YYYY-MM-DD. Default from + 90 days, max from + 366 days. | |
| from | No | Start date YYYY-MM-DD. Default today; past dates are moved to today. | |
| lang | No | Language of the returned bjjsquare.com links: it, en, es, pt, fr or de. Default en. | |
| limit | No | Max results. Default 5, max 10. | |
| country | No | ISO 3166-1 alpha-2 code. Omit for worldwide. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine non-schema context: a hard cap of 10 results per call and the fact that each result carries the official organizer page for registration plus a BJJ Square list page — useful for deciding whether this call is sufficient or a follow-up is needed.
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?
Front-loaded with the purpose, then the source provenance, then the filter and return shape. The parenthetical list of federation names is slightly expendable, but every sentence still carries information an agent would otherwise have to guess.
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 correctly takes on the burden of explaining returns (max 10 per call, each with organizer page and calendar page) and the filter dimensions. What it omits — pagination or how to get beyond the 10-result cap beyond a vague pointer to the calendar page — is minor but real.
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 every parameter (from, to, country, lang, limit) is documented inline with patterns, defaults and bounds. The description only restates 'search by country and date range' and adds no syntax or format 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 specific verb and resource ('Upcoming BJJ and grappling competitions') and immediately scopes the data source as an aggregated public calendar with named feed providers. It is trivially distinguishable from find_gyms/get_gym/list_places, which cover different entities.
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 operating context: 'Search by country and date range,' which maps to the primary filters. It does not name a when-not condition or an alternative tool, but the sibling set (gyms, places) does not overlap with competitions, so no routing ambiguity is left open.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Brazilian jiu-jitsu and grappling gyms by city, by country, or near a point. Give at least one of: city, country, or lat+lng. Returns at most 25 gyms per call (no pagination: narrow the area for more specific results). Each gym has a link to its public page on bjjsquare.com, where contacts and full details are shown. Use get_gym with the slug for the class schedule and what the gym offers.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude of a named place to search around (a city, neighbourhood or landmark). Not the user's own position. Rounded to 2 decimals (about 1 km). | |
| lng | No | Longitude of the same named place. Rounded to 2 decimals. | |
| city | No | City name, in the local language or in English (e.g. "Milano" or "Milan"). | |
| lang | No | Language of the returned bjjsquare.com links: it, en, es, pt, fr or de. Default en. | |
| limit | No | Max results. Default 10, max 25. | |
| country | No | ISO 3166-1 alpha-2 country code, e.g. IT. Recommended with city, to avoid same-name cities. | |
| radius_km | No | Search radius around lat/lng in km. Default 25, max 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and a closed world, so safety is covered. The description adds genuinely new behavioral context beyond them: a hard 25-result ceiling, no pagination, and the fact that results link out to bjjsquare.com for contacts and full details. Minor gap: no mention of auth requirements or error behavior when no filter is supplied.
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 compact sentences, front-loaded with purpose and the calling constraint before the cap and the hand-off to get_gym. The only near-repeat is the 25-result cap, which the schema also encodes, but the accompanying 'no pagination' clarification 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?
With no output schema, the description still tells the agent what comes back: a bounded list of gyms, each linking to a public bjjsquare.com page holding contacts and details. Combined with the annotations and full schema coverage, an agent has everything needed to call this correctly on the first try.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds a cross-parameter constraint the schema cannot express — at least one of city, country, or lat+lng must be supplied — which is real semantic value. It does not, however, add format guidance for the geo pair beyond what the schema already documents.
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 ('Find Brazilian jiu-jitsu and grappling gyms') plus the three supported search modes (city, country, or near a point). It is clearly distinguishable from find_competitions and get_gym, and the description even routes to get_gym for a different resource (schedules).
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 calling precondition ('Give at least one of: city, country, or lat+lng') and names the alternative tool plus the trigger for switching ('Use get_gym with the slug for the class schedule'). It also explains how to work around the cap (narrow the area), which is actionable guidance rather than inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public details of one gym by its slug (from find_gyms): address, website, affiliation, what it offers, class schedule when the gym has published one, and when the schedule was last updated. Only known facts are returned: a missing field means unknown, not "no". Phone and email are on the gym page linked in the result.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the returned bjjsquare.com links: it, en, es, pt, fr or de. Default en. | |
| slug | Yes | Gym slug, e.g. as returned by find_gyms. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered. The description adds real behavioral context beyond that: 'a missing field means unknown, not "no"' disambiguates null semantics, and the note that phone/email live on the linked gym page explains an intentional omission. It does not cover behavior on an unknown/invalid slug.
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, front-loaded with the field list, then the unknown-vs-absent rule, then the phone/email caveat. Every sentence conveys information an agent would otherwise have to guess.
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 the return-shape burden and does so by enumerating returned fields and clarifying null semantics. Combined with annotations covering safety, an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both slug and lang are already documented in the schema. The description reinforces slug provenance but adds no syntax or format detail beyond the schema, and never mentions the lang parameter or its default. 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+resource ('Public details of one gym by its slug') and enumerates exactly what is returned: address, website, affiliation, offerings, schedule, last-updated timestamp. It also distinguishes itself from the sibling find_gyms by naming it as the source of the slug.
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 ties usage to find_gyms ('slug (from find_gyms)'), making the lookup-after-search workflow clear, and the 'public details' framing implies the non-authenticated read case. It stops short of explicit when-not-to-use guidance or naming alternatives for other lookup needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Countries covered by BJJ Square with gym counts, or, with a country code, the cities of that country with gym counts (largest 200). Use it to check coverage before find_gyms.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of the returned bjjsquare.com links: it, en, es, pt, fr or de. Default en. | |
| country | No | ISO 3166-1 alpha-2 code. Omit to list countries. |
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 the 200-city limit detail, 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?
One dense sentence covering both modes and the city limit, plus a short usage sentence. Efficient and front-loaded, though the first sentence is somewhat packed.
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 a read-only tool with full annotation coverage, 2 well-documented parameters and no output schema, the description covers the essential modes and limits. The return structure (gym counts) is mentioned, though not detailed.
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 are fully documented in the schema. The description only explains the mode switch based on the country parameter, which the schema already implies. 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?
States a specific verb+resource ('list covered places') and clearly distinguishes two modes: countries by default, cities when a country code is given. This differentiates it from siblings find_gyms and get_gym.
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 says 'Use it to check coverage before find_gyms', giving clear when-to-use context. It doesn't name when not to use it, but the alternative is obvious from the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_gyms2 fields changedInput schema / properties / lat / descriptionPrevious value: -"Latitude of the search center."New value: +"Latitude of a named place to search around (a city, neighbourhood or landmark). Not the user's own position. Rounded to 2 decimals (about 1 km)."Input schema / properties / lng / descriptionPrevious value: -"Longitude of the search center."New value: +"Longitude of the same named place. Rounded to 2 decimals."find_competitionsfind_gymsget_gymlist_placesBJJ gym, coach, event, and city data for AI agents. Free base tools, x402-paid premium.
Find BJJ clubs, branch details, classes, plans, and prices; manage attendance and trial inquiries.
Find US BJJ gyms with weekly schedules, open mats, and visitor drop-in prices.
Read-only MatFlow data: pricing, competitors, features, FAQs for combat-sports gyms.
Add one secure layer between your agents and this server.
