BJJ and grappling gyms worldwide, plus upcoming competitions. Free, read-only.
Scored across 4 tools
Each tool targets a distinct resource or action: competitions, gym search, gym detail by slug, and place coverage. The descriptions clearly explain boundaries, such as using list_places before find_gyms and get_gym with the slug from find_gyms.
All names follow a consistent verb_noun snake_case pattern: find_competitions, find_gyms, get_gym, list_places. There is no mixing of conventions or vague verbs.
Four tools is well-scoped for a read-only BJJ directory: two finders, one detail getter, and one coverage helper. Each tool has a clear purpose and no redundant operations.
The surface covers places, gyms, and competitions with reasonable workarounds for missing pagination. A minor gap is the lack of a dedicated competition detail tool, though results link to the organizer for full information.
Upcoming BJJ and grappling competitions from federation and organizer calendars (IBJJF, AJP, Smoothcomp and others), by country and date range. Returns at most 10 per call with the link to the organizer for registration, 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 readOnlyHint, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a hard cap of 10 results per call and the fact that each result carries a registration link plus a fallback calendar URL for the complete 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 sentences, zero filler. The scoping axes (sources, country, date range) come first and the return behavior second, which is a sensible front-loaded structure.
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 burden of describing returns and does so: result cap, per-result registration link, and a full-list fallback URL. Combined with annotations covering safety and the 100%-covered schema, an agent has everything needed to call and interpret this 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 all five parameters (including defaults, patterns, enum for lang, and the max-10 limit) are already documented. The description only reinforces the country/date-range and result-cap semantics rather than adding syntax or format detail, 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 ('Upcoming BJJ and grappling competitions'), names the data sources (IBJJF, AJP, Smoothcomp), and scopes it by country and date range. This clearly distinguishes it from siblings like find_gyms and list_places without needing to open any schema.
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 context on what it returns and the key selection axes (country, date range, federations), plus a note to use the BJJ Square calendar page for the full list. It stops short of explicit when-to-use/when-not guidance or naming a sibling alternative, so it is clear but not fully directive.
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 the search center. | |
| lng | No | Longitude of the search center. | |
| 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 this is a read-only, idempotent, non-destructive lookup, so safety is covered. The description adds real behavioral context beyond the annotations: a hard cap of 25 results per call and the absence of pagination, with the workaround ('narrow the area'). It stops short of describing result ordering or what fields come back, hence not 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 sentences, all load-bearing: search modes, input constraint, return-cap behavior, and the handoff to get_gym. The input constraint appears early, before the return semantics, which is the right front-loading for a search 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?
There is no output schema, so the description must carry return semantics, and it does: result count cap, no pagination, and that each gym carries a link to a public page holding contacts and full details. Combined with annotations and a fully documented schema, an agent has everything needed to call and interpret this 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 the baseline is 3. The description adds meaning the schema does not: that city/country/lat+lng are alternative rather than required inputs, and the practical workaround for the result cap. It doesn't restate the enum, radius, or default values, which is appropriate since the schema handles them.
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. It also distinguishes itself from the sibling get_gym by name, so an agent can route correctly without opening either schema.
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 precondition ('Give at least one of: city, country, or lat+lng') and names the alternative tool for a different need ('Use get_gym with the slug for the class schedule and what the gym offers'). When-to-use and when-to-use-something-else are both covered.
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_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.
