Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Comunio MCP Show my current squad and the best market bargains."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for Comunio, the online football fantasy manager.
It gives an AI assistant access to your league — squad, market, offers, standings, transfers — and
lets it act on your behalf: bid, sell, set the lineup. One line, client ↔ MCP ↔ Comunio, and this
is the middle segment.
Status: in daily use against a real account. Nineteen tools: reading the squad, market, offers, standings and transfers, and acting on the market, bids and lineup. It talks to Comunio's unofficial API, which can change without notice — see docs/comunio-api.md for what is mapped and what is not.
Tools come in two kinds, and the name tells you which:
Kind | Naming | What it does |
Read |
| Query only. Never changes anything. Always safe. |
Write |
| Changes your team or spends your money. |
Two properties fall out of that:
There is no AI model inside this server, and no strategy either. It translates: it makes
Comunio's API callable and its answers legible — unpicking slot numbers, the five different ways one
endpoint writes "no data", a ranking field that is 0 for every row. Which player to buy is left to
the assistant you are already talking to. No API key, no GPU, no inference cost.
Your client asks before it acts. Every mutating tool declares itself as one, so your MCP client knows to stop and ask you first. The server does not second-guess a move once you have agreed to it, and it reports what Comunio actually answered rather than assuming it worked.
Related MCP server: Fantasy Premier League MCP Server
A Comunio account. There is no API key and no sign-up — the server logs in as you.
Nothing else needs to be installed on the host.
The image is published, so there is nothing to clone and nothing to build. Put your credentials in a file only you can read, rather than in a command your shell will remember:
install -m 600 /dev/null ~/.comunio.env
$EDITOR ~/.comunio.env # COMUNIO_USERNAME=you
# COMUNIO_PASSWORD=...
claude mcp add comunio -- docker run -i --rm \
--env-file "$HOME/.comunio.env" \
ghcr.io/josetorronteras/comunio-mcpThen ask your assistant how your team is doing — get_account is the quickest proof that
the credentials work.
For Claude Desktop, for the uvx route that skips Docker entirely, and for what each
variable does, see docs/setup.md.
Setup — running the image and connecting it to an MCP client
Tools — what each tool returns and what it touches
Development — layout, dev commands, SDK gotchas
Architecture — design decisions and the reasoning behind them
Comunio API — authentication, the link index and what is still unmapped
MCP protocol notes — the parts of MCP 2026-07-28 that shape this project
Changelog — what changed in each release
Issues and pull requests are welcome. CONTRIBUTING.md covers the setup, what belongs in the server and what does not, and the rules that are not negotiable — no credentials, no tokens and no real account data in a commit. Vulnerabilities go through SECURITY.md rather than a public issue.
Releases follow semantic versioning, and what it covers is the MCP surface: tool names, their input schemas, and the fields their responses carry. Renaming a tool, dropping a parameter or removing a field from a response is a major version. Adding a tool, an optional parameter or a field is a minor one.
What it cannot cover is Comunio. This talks to an unofficial API that can change or break without notice, and no version number here can promise otherwise. When it does change, the fix ships as a patch or a minor — the tools stay the same shape.
MIT.
Unofficial project, not affiliated with Comunio. Use it with your own account and at your own risk.
Accept an offer for one of the manager's players, selling them.
This cannot be undone. Unlike a bid, which queues until the transfer round and can be withdrawn, an acceptance takes effect the moment it is made. The player leaves the squad and there is nothing to reverse it with.
Get the user's explicit agreement first, and tell them two things before asking:
who is being sold, and how the price compares to what the player is worth.
get_offers reports that as premium and premium_pct — a negative value means
the offer is below the player's market value, which is common and easy to miss.
Ids come from get_offers; only offers whose direction is incoming can be
accepted. The player and the price are taken from the offer itself, never passed
in, so what is accepted is exactly what was offered.
Check ok and message in the result. Comunio can report overall success while
rejecting the acceptance itself.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio accepted this particular acceptance |
| buyer | No | Who bought the player |
| price | Yes | What was received for them, in euros |
| player | No | That player's name |
| message | No | Comunio's reason, when it gives one |
| premium | Yes | Price minus the player's quoted value. Negative means sold below what they were worth. |
| offer_id | Yes | The offer that was accepted |
| player_id | Yes | Player who has left the squad |
| premium_pct | Yes | The same difference as a percentage |
| applied_immediately | Yes | True for an acceptance: it takes effect at once and cannot be reversed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes far beyond: it explains the action cannot be undone, takes effect immediately (unlike queued bids), and warns that Comunio can report overall success while rejecting the acceptance (check `ok` and `message`). These are critical behavioral nuances not present in 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?
The description is well-structured and front-loaded: the purpose is in the first sentence, followed immediately by the irreversible warning, then a logical flow covering user guidance, source of IDs, and result checking. Every sentence adds value with no redundancy or filler.
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 description is complete for a single-parameter irreversible action. It covers the parameter source and constraints, the user consent procedure, the premium info needed for user communication, and the correct interpretation of the result (`ok`/`message`). Given the tool's complexity and the presence of an output schema, nothing essential is missing.
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 schema only defines `offer_id` with no description (0% coverage), but the description compensates by stating IDs come from `get_offers` and only incoming offers are acceptable. It also clarifies the player and price are taken from the offer itself, not passed separately, so the semantics of the single parameter are fully explained. A 4 is appropriate because it doesn't re-explain the primitive type but gives all necessary context.
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 opens with a clear verb+resource: 'Accept an offer for one of the manager's players, selling them.' It actively differentiates from sibling tools like place_bid/withdraw_bid by contrasting with a bid ('Unlike a bid...'), so an agent can immediately know this is the accept action, not a bid action.
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?
Provides explicit when-to-use guidance: 'Get the user's explicit agreement first' and tells the agent what to tell the user (who is sold and how price compares via premium/premium_pct). It also states a clear precondition: only offers with direction 'incoming' can be accepted, and warns about the irreversible nature and the need to check result fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the amount of a bid the manager has already placed.
This changes what the manager has committed. Confirm the new amount with the user before calling it, and say what the old one was.
Ids come from get_offers; only offers whose direction is outgoing can be
changed. The player is taken from the offer itself rather than passed in, so a
change cannot end up pointing at a different player.
Like a new bid, the change waits for the next transfer round and can still be
pulled with withdraw_bid until then.
Refused before anything is sent if the id is unknown or if it belongs to an offer
for one of the manager's players. The new amount is not checked against credit:
Comunio enforces that itself and answers per item, so read ok and message.
Check ok and message in the result rather than assuming success.
| Name | Required | Description | Default |
|---|---|---|---|
| price | Yes | ||
| offer_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether this particular bid was accepted by Comunio |
| price | Yes | Amount bid, in euros |
| player | No | That player's name |
| message | No | Comunio's reason, when it gives one |
| offer_id | No | The offer Comunio created. Needed to change or withdraw it. |
| player_id | Yes | Player the bid is for |
| credit_after | No | Spending power left if every open bid wins, in euros. Accounts for the other bids, which Comunio's own `credit` figure does not. |
| credit_committed | No | Already tied up in the manager's other open bids, in euros |
| applied_immediately | Yes | False for a bid: it waits for the transfer round and can be withdrawn |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations, warning that this changes the manager's commitment, advising confirmation with the user, noting the old amount should be stated, explaining the transfer-round delay, and listing refusal conditions such as unknown IDs or offers for the manager's players. It also discloses that the credit check is deferred to Comunio and directs the user to read ok and message.
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 structured in short, purposeful paragraphs, with the most critical warning front-loaded in bold. Every sentence adds operational value: source of IDs, constraints, timing, refusal behavior, and result checking. Nothing is redundant.
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 mutating tool with minimal annotations and an output schema present, the description is remarkably complete. It covers when to call it, where inputs come from, what side effects occur, when it can be undone, failure conditions, and how to interpret the response via ok and message.
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 0%, so the description must compensate. It does: offer_id is tied to get_offers and outgoing-only offers, while price is characterized as the new committed amount with the caveat that credit is not locally validated. It stops short of specifying units or ranges, but the essentials are covered.
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 opens with a specific verb and resource: "Change the amount of a bid the manager has already placed." This clearly distinguishes it from sibling tools like place_bid, withdraw_bid, and accept_offer by focusing on modifying an existing bid rather than creating or removing one.
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 gives practical usage context: offer IDs come from get_offers, only outgoing-direction offers can be changed, and the player is inferred from the offer itself. It does not explicitly name place_bid as the alternative for new bids, but the phrase "already placed" and the comparison "Like a new bid" make the intended boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change what the manager is asking for a player they already have listed on the market.
This changes the manager's team. Confirm the player and the new price with the
user before calling it. The player must already be listed — use
list_player_on_market first if they are not; this tool cannot put anyone up for
sale.
This sets the manager's own asking price. It has nothing to do with the
recommended_price that get_market and get_player report, which is Comunio's
suggestion and cannot be changed.
Comunio answers with a bare true here rather than any detail, so ok is all
there is to go on.
| Name | Required | Description | Default |
|---|---|---|---|
| price | Yes | ||
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio accepted the change |
| price | Yes | The asking price that was requested, in euros |
| player_id | Yes | Player whose price was changed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations cover the base mutation profile, but the description adds useful behavioral context: the call changes the manager's team, it cannot list an unlisted player, and the response from Comunio is only a bare `true`. This does not contradict any annotation.
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 front-loaded with the main action and uses short, bolded sections for preconditions, side effects, and output behavior. It is not the shortest possible description, but every section adds relevant information for correctly using the 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 two-parameter mutation tool, the description covers the operation, the prerequisite, the user-confirmation requirement, the distinction from `recommended_price`, and the actual response shape. Given the annotations and output schema, the agent has enough context to call the tool safely and 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 description coverage is 0%, so the description carries the semantic load. It explains that `price` is the manager's own asking price and that `player_id` must refer to an already-listed player. It does not mention possible price constraints, but the core meaning of both parameters is covered.
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 first sentence states a specific action and resource: change the asking price for a player already listed on the market. It explicitly distinguishes itself from `list_player_on_market` by saying it cannot put anyone up for sale, so an agent can tell exactly what this tool does.
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 clearly gives a prerequisite: the player must already be listed, and `list_player_on_market` should be called first if not. It also provides a safety guideline to confirm the player and new price with the user before invoking the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the manager's current budget, squad totals and formation, plus the league rules that decide which moves are legal.
Start here. budget bounds any bid, tactic and team_count_linedup say what
the lineup looks like now, and the rules cover bidding mechanics (notably
second_highest_offers), sale limits and bans.
Read-only: fetches current state and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| account | Yes | |
| community | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only: fetches current state and changes nothing.' It adds some context beyond the annotation by explaining how the returned data constrains other moves, but it does not disclose additional behavioral traits such as rate limits or potential staleness.
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 front-loaded with the core purpose, then immediately gives actionable guidance ('Start here') and the key fields an agent needs to interpret. The read-only note is short and reinforces safety. Every sentence earns its place with no filler.
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 zero-parameter tool with an output schema present, the description fully covers what the agent needs: the returned data categories, how they relate to legal moves, and the read-only nature. The mention of specific rule details like `second_highest_offers` gives meaningful context without needing to enumerate the output schema.
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 has zero parameters, and the input schema confirms this with an empty properties object. With 100% schema coverage and no parameters to document, the description's lack of parameter-specific detail is appropriate; the baseline of 4 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?
The description states a specific verb and resource: 'Get the manager's current budget, squad totals and formation, plus the league rules that decide which moves are legal.' It clearly differentiates this from sibling tools like get_squad and get_player by enumerating the distinct data it returns.
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 explicitly says 'Start here' and explains why: `budget` bounds any bid, `tactic` and `team_count_linedup` describe the current lineup, and the rules cover bidding mechanics, sale limits, and bans. This gives clear context for when to call this tool first, though it does not explicitly name alternative tools or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get every player currently up for sale, with prices, price trend and who is selling.
closes_at is when the current round of transfers is processed — bids have to be
in before it. Per listing, from_computer marks players Comunio is selling itself
rather than a rival, is_mine marks the manager's own listings, which are not
buyable, and trend shows which way the price is moving.
Compare quoted_price against recommended_price to judge an asking price, and
check get_account for the budget that bounds any bid.
Read-only: fetches current state and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| listings | Yes | |
| closes_at | No | When the current round of transfers is processed. Bids must be in by then. |
| daily_transfers_processed | Yes | Whether today's transfer round has already run |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only: fetches current state and changes nothing,' which aligns with and reinforces the readOnlyHint annotation. It also explains key behavioral aspects of the data: closes_at timing, from_computer, is_mine, and trend semantics. This adds value beyond the annotation by clarifying what the returned fields mean and the timing constraint for bids.
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 well-structured and front-loaded: the first sentence states the core function, followed by a compact explanation of field semantics, and ends with a clear read-only note. Every sentence adds value, and the use of backticks for field names improves scannability. It's appropriately sized for the tool's complexity.
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 the tool has no parameters and an output schema exists, the description covers the essential context: what the tool returns, how to interpret the data, the timing constraint, and the read-only nature. It also provides a cross-reference to get_account for budget, which is useful for an agent deciding how to act on the data. Nothing critical is missing.
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 has zero parameters, so the schema provides no parameter documentation. The description compensates by explaining the meaning of key fields in the response (closes_at, from_computer, is_mine, trend, quoted_price, recommended_price). Since there are no parameters to document, the description's focus on output semantics is appropriate and valuable.
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 tool's function: retrieving every player currently for sale, with prices, price trend, and seller. It distinguishes itself from siblings like get_transfers and get_offers by focusing on the market listings, and the title 'Transfer market' reinforces the resource. The verb 'Get' is specific and the scope is unambiguous.
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 provides clear context on when to use this tool: to view the market and judge asking prices. It references get_account for budget context, which helps an agent understand a related workflow. However, it doesn't explicitly state when NOT to use it or name alternatives like get_transfers or get_offers, so it falls slightly 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.
Get the league news feed, newest first: what has happened in this community.
Announcements from Comunio and from the community admin, members joining, the league being reset, lineups being changed, and transfer rounds settling. Use it to answer "what has been going on" or to find out why something changed — a reset, a rule change or a new member explains a lot that the squad and market do not.
Each entry has a type. The ones seen so far are SYSTEM_ADMINISTRATION (Comunio's
own announcements, such as when a matchday starts), COMMUNITY_ADMINISTRATION (the
admin resetting or reconfiguring the league), MEMBER_ADMINISTRATION (someone
joining), LINEUP_CHANGED and TRANSACTION_TRANSFER. It is an open set, so treat
an unfamiliar one as news rather than an error.
On administration entries the whole announcement is in title and text is null.
Read title first and treat it as content, not as a label.
For transfer entries this gives only how many moves there were. Use
get_transfers for the players, the prices and who was on each side — it parses
the same entries properly.
types filters to the kinds asked for, matched case-insensitively; leave it out to
get everything. limit caps how many entries come back, one page by default, and a
larger value costs one extra request per page.
Read-only: fetches the feed and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| types | No |
| Name | Required | Description |
|---|---|---|
| entries | Yes | Newest first |
| summary | Yes | |
| has_more | Yes | Whether older entries exist beyond what was fetched |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses substantial behavior: newest-first ordering, an open set of entry types, null 'text' on administration entries, transfer entries containing only counts, and the per-page request cost of larger limits. This is far more than annotations alone provide.
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 longer than necessary for a simple feed tool, but the length is justified by the non-obvious type semantics, null-field behavior, transfer-vs-get_transfers distinction, and per-page cost. It is front-loaded with the core purpose and organized into clear sections. Slight redundancy exists around read-only behavior, but otherwise 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?
Given the output schema exists, the description does not need to spell out return shape. It covers purpose, usage, parameter semantics, type behavior, edge cases, alternatives, and the read-only safety profile. An agent has everything needed to invoke and interpret results 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 description coverage is 0%, so the description carries the full burden for the two parameters. It explains that 'types' filters case-insensitively and can be omitted for everything, and that 'limit' caps entries with a default page and an extra-request cost. It also documents the known type values.
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 opens with a specific verb and resource: 'Get the league news feed, newest first' and immediately states what it contains. It also differentiates itself from get_transfers by explicitly saying transfer entries only give move counts and that get_transfers parses them properly.
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 tells the agent when to use this tool ('what has been going on', 'find out why something changed') and explicitly routes transfer-related detail to get_transfers. It also gives concrete guidance on types and limit, including when to omit them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get every open transfer offer, and the manager's spending power.
credit is what can actually be spent and is not the same as the budget in
get_account: the league's credit factor lets it exceed cash in hand. Use this
number when sizing a bid.
Each offer says which way it goes — incoming when somebody wants one of the
manager's players, outgoing when the manager is bidding — and how the price
compares to the player's market value, via premium and premium_pct. A negative
premium is an offer below what the player is worth.
Read-only: fetches current state and changes nothing. Accepting, declining or withdrawing an offer is not possible through this tool.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| credit | Yes | What the manager can actually spend. Not the same as budget: the league's credit factor lets it exceed cash in hand. |
| offers | Yes | |
| summary | Yes | |
| has_more | Yes | Whether Comunio is holding back further pages |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces it ('Read-only: fetches current state and changes nothing'). It adds valuable behavioral context about the credit field vs budget and the meaning of incoming/outgoing and premium. Since output schema exists, the description need not cover return details. It does not contradict annotations and adds substantive semantic information.
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 organized into a clear intro, a paragraph on credit, a paragraph on offer details, and a read-only note. Every sentence serves a purpose, and the most critical fact (what the tool returns) is front-loaded. No redundancy or filler.
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 an output schema present, the description covers everything an agent needs: the data returned (offers and spending power), the key distinction (credit vs budget), the meaning of incoming/outgoing and premium, and the read-only constraint. It is complete for the tool's simplicity.
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 has zero parameters, so the baseline is 4. The description appropriately spends no space on parameters. It does not need to explain anything beyond what the schema already conveys (nothing), and it adds value through the credit and premium explanations instead.
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 opens with a precise verb and resource: 'Get every open transfer offer, and the manager's spending power.' It clearly distinguishes itself from siblings like get_account by explaining that credit differs from budget, and it defines the semantics of incoming/outgoing and premium. An agent can immediately understand what the tool does.
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 explicitly tells when to use the credit number ('Use this number when sizing a bid') and contrasts it with get_account. It also states what the tool cannot do ('Accepting, declining or withdrawing an offer is not possible through this tool'), giving clear when-not guidance. This goes beyond vague context to provide actionable direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get everything Comunio knows about one player. Ids come from get_squad,
get_market or get_offers.
Beyond the price and availability the squad already gives: season-by-season
history going back years, the record of goals, cards and man-of-the-match
awards, averages including a recent-form window, the next three fixtures, what
the current owner paid, and the buyout_clause — what taking the player from
their owner without consent would cost.
status_meaning spells out the status code, and available is true only when the
player can actually be counted on.
Read-only: fetches current state and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| club | Yes | |
| name | Yes | Player name |
| owner | No | Manager who owns the player |
| price | Yes | Current market value, in euros |
| record | Yes | |
| status | Yes | Availability code, e.g. ACTIVE or YELLOW_RED_BANNED |
| history | Yes | Points season by season, oldest first, as Comunio orders them |
| profile | Yes | |
| watched | Yes | On the signed-in manager's watchlist |
| averages | Yes | |
| owner_id | No | That manager's identifier |
| available | Yes | Whether the player can be counted on right now |
| player_id | Yes | Player identifier |
| last_points | No | Points in the last matchday |
| status_info | No | Comunio's note on the status |
| next_matches | Yes | Upcoming fixtures, soonest first |
| purchased_on | No | When the owner bought them, or null for a player from the initial draft who was never bought |
| total_points | No | Points this season |
| buyout_clause | Yes | |
| purchase_price | No | What the current owner paid, in euros |
| status_meaning | No | Plain-language reading of the status code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only: fetches current state and changes nothing.' It goes beyond the annotation by detailing what data is returned (history, record, averages, etc.), which is useful behavioral context. No contradictions; it accurately reflects the tool's non-mutating nature.
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 well-organized and front-loaded: the first sentence states the purpose, followed by a paragraph listing key data fields, then status/availability, and finally the read-only guarantee. Every sentence adds value with no fluff. The use of backticks for field names aids readability.
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 has an output schema (present but not shown), so the description need not detail every return field, but it lists the most important ones (history, record, averages, fixtures, buyout_clause, status_meaning, available). It also covers read-only behavior and ID sourcing. For a single-parameter getter, this is complete enough; it doesn't mention error cases, but that's acceptable given the schema and read-only nature.
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%, so the description must compensate. It does by stating 'Ids come from get_squad, get_market or get_offers,' which tells the agent exactly where to obtain the player_id. While it doesn't explicitly define player_id, the source hint is valuable and beyond the schema's bare integer type. It's sufficient for a single obvious parameter.
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 opens with a clear, specific action: 'Get everything Comunio knows about one player.' It distinguishes itself from siblings by explicitly stating it provides more than the squad's price/availability, and by listing the additional data fields (history, record, averages, fixtures, buyout clause). This makes the tool's unique purpose immediately obvious.
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 tells the agent where player IDs come from ('get_squad, get_market or get_offers'), which implies these tools should be used first. It also contrasts with get_squad by saying 'Beyond the price and availability the squad already gives,' suggesting get_player is for deeper data. However, it does not explicitly state when NOT to use it (e.g., when only basic info is needed), so it's clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get every player in a squad, with availability, scoring, prices and lineup state. Defaults to the signed-in manager's own squad.
Pass manager_id to inspect a rival's squad instead — the ids come from
get_standings. Rival squads are fully visible: prices, injuries and depth. What
is not visible is recommended_price, which Comunio only gives for your own
players.
Per player: position and club; status with status_info naming an injury;
points, last_points and average_points; quoted_price and
recommended_price; whether they are linedup or a substitute; whether they
are on_market; and next_match with its kick-off time.
summary counts what lineup rules are checked against, tactic is the formation
set, and is_mine says whose squad came back.
Read-only: fetches current state and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| manager_id | No |
| Name | Required | Description |
|---|---|---|
| owner | No | Manager the squad belongs to |
| tactic | Yes | Formation the lineup is set up for, e.g. '442' |
| is_mine | No | Whether this is the signed-in manager's own squad |
| players | Yes | |
| summary | Yes | |
| owner_id | No | That manager's identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces it with 'Read-only: fetches current state and changes nothing.' Beyond that, it discloses detailed behavioral aspects: per-player fields (status, points, prices, lineup state), what is hidden for rival squads (recommended_price), and the presence of summary, tactic, and is_mine. This is substantial added context beyond the annotation.
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 well-structured with a clear lead sentence, a dedicated paragraph for the parameter usage, a bullet-like enumeration of player fields, and a closing read-only note. Every sentence adds value, and the most critical information (purpose and parameter usage) 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?
With only one optional parameter and an output schema present, the description provides a thorough high-level overview of the response structure (per-player details, summary, tactic, is_mine) and covers edge cases like rival squad visibility. Nothing essential for calling the tool correctly is missing.
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 the description fully compensates. It explains that manager_id is optional, defaults to null (own squad), and provides guidance on obtaining valid ids via get_standings. This gives the parameter meaning beyond the bare integer/null schema definition.
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 opens with a precise verb-resource statement: 'Get every player in a squad, with availability, scoring, prices and lineup state.' It distinguishes itself from siblings by explaining the optional manager_id path for rival squads and referencing get_standings for ids, so an agent can tell it apart from get_player or get_market.
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 explicitly says it defaults to the signed-in manager's own squad and instructs to pass manager_id to inspect a rival's squad, with a pointer to get_standings for valid ids. It also clarifies what is and isn't visible for rivals, leaving no ambiguity about when to call this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the league table: every manager with their points, squad value and whether their budget is in the red.
Rows come best first, with rank filled in and is_me marking the signed-in
manager, and manager_id can be used to look up a rival's squad.
period picks which table. total is the season standings. live is the one
to ask for while a matchday is being played: only it fills live_points and
players_possibly_scoring, and only it reports negative_budget correctly —
under total that flag reads false for everyone, including managers who are
actually in the red and will therefore score nothing this matchday.
Read-only: fetches current state and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | total |
| Name | Required | Description |
|---|---|---|
| rows | Yes | Managers, best first |
| period | Yes | Period the table covers, e.g. 'total' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by explaining that the tool changes nothing, which fields only `live` populates, and the surprising caveat that `negative_budget` is unreliable under `total`. This gives the agent important behavioral knowledge that annotations alone do not convey.
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 detailed yet tightly organized: it opens with the core purpose, then describes row contents, then explains period semantics and the critical caveat, and closes with the read-only guarantee. Every sentence contributes useful operational information without redundancy.
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 single-parameter read-only tool with an output schema, the description is complete: it names the key output fields, explains the parameter's behavior, flags the negative_budget limitation, and confirms no side effects. An agent has everything needed to invoke 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 description coverage is 0%, but the description fully compensates by explaining both enum values: `total` is the season standings, while `live` is matchday-aware and correctly reports `negative_budget`. It adds meaning far beyond the bare enum names and default value in 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: 'Get the league table' and elaborates exactly what it contains: manager points, squad value, and budget status. It is immediately distinguishable from sibling tools, which concern players, bids, transfers, and squads rather than standings.
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 clearly explains when to use `total` versus `live`, explicitly telling the agent that `live` is the table to request during an in-progress matchday. It does not name alternative sibling tools, but no sibling offers standings, so the period-level guidance is the relevant usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get transfers that have already completed, newest first, with what was actually paid.
This is settled prices rather than quotes: what players really went for in this
league. Use it to calibrate a bid, since the market only says what a player is
listed at. Each transfer also carries quoted_price, what the player was valued
at, so paying over or under the odds is visible without another call.
from_computer means bought from Comunio, to_computer sold back to it, and
involves_me marks the signed-in manager's own deals. offered_at is when the
bid went in and settled_at when it went through. summary totals each kind and
the money that changed hands.
limit caps how many transfers come back and defaults to 20, which is a default
rather than a maximum: this endpoint returns as many as it is asked for. Raise it
to look further back — a larger value costs one extra request only when there is
more history than one page holds.
Read-only: fetches history and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| has_more | Yes | Whether older transfers exist beyond what was fetched |
| transfers | Yes | Newest first |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses behavior beyond the readOnlyHint annotation: it is stated as 'Read-only: fetches history and changes nothing', which reinforces the annotation. It also elaborates on the `limit` parameter's default behavior, clarifying that it is a default, not a maximum, and explains that a larger value may cost one extra request when history exceeds one page. This adds valuable behavioral context that is not apparent from the schema alone.
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 well-structured and front-loaded with the primary purpose. It uses clear paragraphs to explain the tool's purpose, field meanings, and parameter behavior without redundancy. Every sentence serves a purpose, adding new information rather than restating what the title or schema already provides. It is concise yet comprehensive.
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 the tool's simplicity (one optional parameter) and the presence of an output schema (which the description does not need to repeat), the description is complete. It explains the tool's purpose, usage context, field semantics, and parameter behavior. It provides all necessary information for an agent to call the tool correctly and interpret results, even without seeing the output schema.
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?
Although the schema has 0% description coveragehol, the description provides rich context for the `limit` parameter, explaining its default, that it is not a maximum, and the potential request cost implications. This goes beyond the schema's basic type and default, giving the agent a clear understanding of how to use the parameter effectively. The description effectively compensates for the lack of schema-level descriptions.
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 what the tool does: it retrieves completed transfers with settled prices rather than quotes. It distinguishes itself from related market tools by emphasizing the 'actual paid' price, which is a specific and meaningful differentiator. This is a clear and specific verb+resource statement.
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 explicitly explains when to use this tool: to calibrate a bid based on actual market prices, contrasting with the market's listed quotes. It also explains the meaning of each field, such as `from_computer` and `to_computer`, which guides correct interpretation. This provides clear context for how the tool fits into the workflow and when it should be chosen over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the players the manager is keeping an eye on.
A shortlist, not a commitment: watching a player does nothing to the squad or the
budget. Use get_market to see which of them are actually for sale.
Read-only: fetches current state and changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| total | Yes | How many players are being watched |
| players | Yes | |
| unowned | Yes | How many of them no manager holds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, and the description reinforces this with 'Read-only: fetches current state and changes nothing.' It adds useful behavioral context beyond the annotation by clarifying that watching a player has no effect on squad or budget, which helps the agent understand side effects.
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 compact, front-loaded with the core purpose, and each sentence contributes meaningful guidance. The read-only sentence slightly overlaps with the annotation but adds plain-language clarity without bloating the definition.
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 zero parameters, an output schema, and a readOnlyHint annotation, the description covers everything needed to invoke the tool correctly: what it returns, what it does not affect, and which sibling covers the related need of sale status.
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 has zero parameters, so there is nothing for the description to clarify beyond the schema. The first sentence confirms the resource being fetched, and the rest of the description adds scope and context where parameter documentation would otherwise be needed.
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 uses a specific verb and resource: 'Get the players the manager is keeping an eye on.' It clearly identifies what a watchlist is and distinguishes it from related tools like get_squad or get_market, so an agent can tell what it returns.
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 provides clear context ('a shortlist, not a commitment') and explicitly points to get_market as the alternative when the agent needs to know which players are actually for sale. It lacks an explicit 'do not use this for X' statement, but the guidance is sufficient for correct routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put one of the manager's own players up for sale at the given asking price.
This changes the manager's team. Confirm the player and the price with the
user before calling it. Ids come from get_squad; get_player gives Comunio's
suggested price for comparison.
Listing is reversible — the player can be taken back off the market — but any offers received in the meantime are real.
Check placed and rejected in the result rather than assuming it worked:
Comunio can refuse an individual player while reporting overall success.
| Name | Required | Description | Default |
|---|---|---|---|
| price | Yes | ||
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| placed | Yes | Player ids that are now listed |
| rejected | Yes | Player ids Comunio refused to list |
| remaining | No | Comunio's own counter from the response. What it counts is not documented and does not match the countdown on market listings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already indicate non-read-only, the description adds significant behavioral context: it mutates the team, is reversible, offers received are real, and it warns about partial failures (checking placed/rejected). This goes well beyond the annotations and gives an agent crucial operational knowledge.
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 front-loaded with the core action, uses a bold warning for critical side effects, and is succinct. Every sentence adds value—confirmation, parameter sourcing, reversibility, and result-checking—without fluff.
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?
It covers the essential workflow: what the tool does, prerequisites (own player, confirmation), input sourcing, side effects, reversibility, and how to interpret results via placed/rejected fields. Combined with the output schema, this is fully adequate for correct invocation.
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 compensates by explaining player_id as one of the manager's own players (sourced from get_squad) and price as the asking price with guidance to compare against get_player's suggested value. This provides meaning beyond the raw schema, though it doesn't specify constraints like positive values (implied by integer type).
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 action ('Put one of the manager's own players up for sale') with a clear resource (player) and price parameter. It is distinct from siblings like unlist_player_from_market or change_listing_price, making its purpose unmistakable.
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 explicitly instructs to confirm the player and price with the user before calling, and provides source context (IDs from get_squad, suggested price from get_player). It lacks explicit exclusions or direct comparisons to sibling tools, but the context is clear enough for an agent to decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bid for a player on the market.
This commits the manager's money. Confirm the player and the amount with the user before calling it, and say what they would have left.
The bid does not take effect straight away: it waits for the next transfer round,
which get_market reports as closes_at. Until then it can be changed with
change_bid or pulled with withdraw_bid.
Sizing the bid: compare against credit from get_offers, not budget from
get_account — the league's credit factor makes them different numbers. Comunio's
credit does not subtract bids already outstanding, so check
credit_committed in the result for what is already promised. What players
actually sell for is in get_transfers; quoted_price is only an asking price.
The amount is not checked against credit here. Comunio enforces its own limit and answers "Credit exceeded", so a bid it would accept is never refused by this tool. Refused before anything is sent only if the player is not on the market or is one of the manager's own listings.
Check ok and message in the result. Comunio can report overall success while
rejecting the bid itself.
| Name | Required | Description | Default |
|---|---|---|---|
| price | Yes | ||
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether this particular bid was accepted by Comunio |
| price | Yes | Amount bid, in euros |
| player | No | That player's name |
| message | No | Comunio's reason, when it gives one |
| offer_id | No | The offer Comunio created. Needed to change or withdraw it. |
| player_id | Yes | Player the bid is for |
| credit_after | No | Spending power left if every open bid wins, in euros. Accounts for the other bids, which Comunio's own `credit` figure does not. |
| credit_committed | No | Already tied up in the manager's other open bids, in euros |
| applied_immediately | Yes | False for a bid: it waits for the transfer round and can be withdrawn |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only mark the tool as non-read-only, non-idempotent, and non-destructive. The description adds essential behaviors beyond that: it commits the manager's money, takes effect only at the next transfer round, does not check credit locally, can be refused only for market/ownership reasons, and can return overall success while the bid itself is rejected. This is exactly the kind of behavioral context an agent needs.
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?
Although long, the description is dense and front-loaded with the most important warning: 'This commits the manager's money.' Every paragraph earns its place by covering a distinct operational concern: confirmation, timing, credit semantics, refusal conditions, and result interpretation. There is no filler or repetition.
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 financial, delayed-effect mutation with two parameters and meaningful failure modes, the description is complete. It covers prerequisites, timing, related tools, credit nuances, refusal conditions, and result checking. It even documents the tricky 'Comunio reports success while rejecting the bid' case, so an agent can handle the full call lifecycle.
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 0%, so the description must compensate for the bare parameter titles. It does: price is the bid amount, not checked against credit, and should be sized against credit; player_id is the player being bid on and is validated against market availability and own listings. It could be even more explicit about units or currency, but the provided guidance is sufficient for a confident 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?
The description opens with a specific verb and resource: 'Bid for a player on the market.' It clearly distinguishes placing a bid from the sibling operations by explaining that the bid waits for the next transfer round and can later be changed with change_bid or withdrawn with withdraw_bid. An agent can tell exactly what this tool does relative to its 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?
The description gives strong contextual guidance: confirm with the user before calling, size the bid against credit from get_offers rather than budget from get_account, and check ok/message afterward. It also mentions alternatives (change_bid, withdraw_bid) for later stages, but it does not explicitly state a when-not-to-use condition for this tool versus an alternative bidding action. Still, the context is clear enough to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the manager's formation and starting eleven.
This replaces the current lineup. Confirm the formation and the players with the user before calling it.
tactic is one of: 442, 343, 352, 433, 451 — read as defenders, midfielders,
strikers. Players are given by position and ids come from get_squad; the slot
numbers Comunio wants are worked out here.
A partial lineup is allowed. Comunio deducts four points for every empty slot, and the result says how many were left and what that costs.
Players who are injured or suspended can still be fielded — Comunio permits it —
so they are not refused, but the result lists them under unavailable. Check
status in get_squad before choosing.
A player can likewise be put in a slot they do not normally play. That is Comunio's
call to accept or refuse, not this tool's: the result lists them under
out_of_position, and ok says what Comunio decided.
Refused before anything is sent if the formation is not one Comunio accepts, if there are more players than the formation has room for (the extras would be dropped in silence), if a player is not in the squad, or if one appears twice.
The lineup can be set again until the matchday starts.
| Name | Required | Description | Default |
|---|---|---|---|
| keeper | No | ||
| tactic | Yes | ||
| strikers | No | ||
| defenders | No | ||
| midfielders | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio accepted the lineup |
| tactic | Yes | Formation the lineup was set to |
| fielded | Yes | Who ended up in which slot |
| empty_slots | Yes | Slots left unfilled |
| unavailable | Yes | Fielded players who were not ACTIVE — injured, suspended and the like |
| penalty_points | Yes | What those empty slots cost, by Comunio's own stated rule of four points each |
| out_of_position | No | Fielded players put in a slot other than the position they play. Reported, not refused: Comunio decides whether it accepts them |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses extensive real behavior: the lineup is replaced, empty slots cost four points each, injured/suspended players can still be fielded, out-of-position selections are passed to Comunio, and certain invalid payloads are refused before being sent. This goes far beyond what annotations alone could convey.
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 dense but efficiently organized: purpose and warning first, then each consequential behavior in its own short paragraph. No sentence is padding, and the length is justified by the number of meaningful edge cases and side effects.
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 the tool's complexity, the description is complete enough for an agent to call it safely. It covers prerequisites, failure conditions, allowed-but-flagged situations, scoring consequences, and timing limits. The existing output schema covers return details such as `ok`, `unavailable`, and `out_of_position`.
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%, so the description must carry the parameter meaning, and it does. It explains that `tactic` values are read as defenders/midfielders/strikers, that players are provided by position, that ids come from `get_squad`, and that a partial lineup is allowed through omitted/nullable position arrays.
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 opens with a specific action and resource: 'Set the manager's formation and starting eleven.' It also immediately disambiguates its effect by saying 'This replaces the current lineup,' which separates it from the many get_* and market tools listed as 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?
It gives explicit preconditions: confirm with the user before calling, get player ids from `get_squad`, and check `status` in `get_squad` before choosing players. It also gives a temporal boundary ('The lineup can be set again until the matchday starts') and explains rejection cases, so an agent knows when a call would fail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take one of the manager's own players back off the market, so it is no longer for sale.
This changes the manager's team. Confirm which player with the user before
calling it. Ids come from get_market, where the manager's own listings are the
ones marked is_mine.
Any offers already received for that player are not cancelled by this — check
get_offers.
Comunio reports no per-player detail here, only an overall status, so unlisted
is what was asked for rather than what was confirmed. Call get_market if it
matters.
| Name | Required | Description | Default |
|---|---|---|---|
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio reported the request as successful |
| unlisted | Yes | Player ids the request asked to take off sale |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by warning that the action changes the team, does not cancel existing offers, returns only an overall status rather than per-player confirmation, and suggesting get_market for verification.
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 compact and well-structured: first sentence states the action, then bolded warnings and follow-up guidance are provided in separate short paragraphs. No filler or repetition.
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?
It covers the source of the required argument, the pre-action confirmation step, the side effect on offers, the response granularity, and the follow-up call to get_market. The description is sufficient for correct and safe invocation.
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 only parameter (player_id) is not described in the schema, but the description compensates by saying IDs come from get_market and are the manager's own listings marked is_mine. It could add a bit more format detail, but the single parameter is fully actionable.
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 uses a specific verb and resource ('Take a player off the market') and clearly scopes it to the manager's own players, making it easy to distinguish from listing, pricing, and bidding operations.
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?
Provides clear procedural context: confirm the player with the user, use IDs from get_market where is_mine identifies own listings, and check get_offers if relevant. It does not explicitly name exclusions or alternative tools, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a player from the manager's watchlist.
Harmless: it changes nothing about the squad, the budget or any offer. Ids come
from get_watchlist.
| Name | Required | Description | Default |
|---|---|---|---|
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio accepted the change |
| watching | Yes | Whether the player is now being watched |
| player_id | Yes | Player added to or removed from the watchlist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly, idempotent, non-destructive. The description adds value by stating the operation is 'harmless' and explicitly listing what it does not affect (squad, budget, offers), plus pointing to the ID source. This goes beyond structured fields without contradicting them.
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 terse sentences cover purpose, side effectsvers and ID source. No redundant phrasing.
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?
Simple one-parameter mutation with idempotent/non-destructive annotations and an output schema. It lacks explicit return behavior but the output schema covers that; the description's guidance on side effects and source of IDs is sufficient.
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 only gives type; description adds that IDs come from get_watchlist, which tells the agent where to find valid values. With 0% schema coverage, this compensation is meaningful, though the parameter itself is self-explanatory.
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: 'Remove a player from the manager's watchlist.' It clearly distinguishes this from the sibling watch_player tool, leaving no ambiguity about the operation's purpose.
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 provides clear context, including the source of valid IDs ('Ids come from get_watchlist'), which tells an agent where to obtain the required input. It doesn't explicitly exclude alternatives, but the operation is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a player to the manager's watchlist.
Harmless: it commits nothing and spends nothing, it only marks the player as one
to keep an eye on. Ids come from get_market, get_squad or get_standings.
| Name | Required | Description | Default |
|---|---|---|---|
| player_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio accepted the change |
| watching | Yes | Whether the player is now being watched |
| player_id | Yes | Player added to or removed from the watchlist |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=falsechers. The description adds domain-level transparency: 'commits nothing and spends nothing, it only marks the player.' This meaningfully clarifies the side-effect profile beyond the raw hint flags.
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 plus a short domain-level clarification. The core action is first, the side-effect note is second, and the ID-source pointer is last. No fluff.
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?
Complete for a one-parameter, idempotent, non-destructive tool with an output schema. It covers the effect, the safety profile, and where to get the only argument; nothing material is missing.
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 0%, so the description must compensate. It does by telling the agent player_id values come from get_market, get_squad, or get_standings. The meaning of 'player ID' is not deeply expanded, but the source guidance is exactly what 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?
States exactly what it does with a specific verb and resource: 'Add a player to the manager's watchlist.' This is unambiguous and clearly distinguishable from sibling tools like get_watchlist.
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?
Clearly implies when to use it: when a player should be monitored. It also tells the agent where valid IDs come from (get_market, get_squad, get_standings). It does not explicitly name alternatives or when-not-to-use conditions, so it stops one step 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.
Withdraw a bid the manager has placed, so it is no longer in the running.
This changes what the manager has committed to. Confirm which bid with the
user before calling it. Ids come from get_offers; only offers whose direction
is outgoing can be withdrawn.
Refuses outright if the id belongs to an offer for one of the manager's players rather than a bid they made. Comunio uses the same request for both, so telling them apart is done here rather than left to chance.
A withdrawn bid cannot be restored, but a new one can be placed while the market is still open.
| Name | Required | Description | Default |
|---|---|---|---|
| offer_id | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Whether Comunio accepted the withdrawal |
| price | No | What the withdrawn bid offered |
| player | No | Who the withdrawn bid was for |
| offer_id | Yes | The offer that was withdrawn |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnly=false, idempotent=false, destructive=false, but the description adds critical behavioral details: it changes what the manager has committed to, is irreversible, and refuses certain inputs. The note that Comunio uses the same request for both directions and the tool disambiguates is valuable beyond structured fields.
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 well-structured: a clear opening sentence, followed by bolded importance, then prerequisites, edge-case handling, and consequences. Every sentence adds value with no fluff, and the key constraints are 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?
Given there is an output schema (not shown but indicated), the description needn't explain return values. It covers prerequisites, valid inputs, refusal behavior, irreversibility, and the ability to re-place a bid. For a single-parameter tool, this is complete and actionable.
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 0%, so the description carries the burden. It fully explains offer_id: where to get it (get_offers), what values are valid (direction=outgoing), and what it represents (a bid made by the manager, not an incoming offer). This adds complete meaning to the single parameter.
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 action ('Withdraw a bid'), the resource ('a bid the manager has placed'), and the outcome ('no longer in the running'). It differentiates from siblings like place_bid and change_bid by specifying it's for outgoing bids only, and explicitly contrasts with incoming offers for the manager's players.
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?
Provides explicit when-to-use guidance: IDs come from get_offers, only offers with direction='outgoing' qualify, and the user should confirm which bid before calling. It also states a clear exclusion (refuses offers for the manager's players) and notes a withdrawn bid cannot be restored but a new one can be placed, giving the agent full decision context.
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.
v1.0.2accept_offerchange_bidchange_listing_priceget_accountget_marketget_newsget_offersget_playerget_squadget_standingsget_transfersget_watchlistlist_player_on_marketplace_bidset_lineupunlist_player_from_marketunwatch_playerwatch_playerwithdraw_bidScored across 19 tools
Each tool name clearly maps to a distinct action or query (e.g., get_squad vs get_standings vs get_market; place_bid vs change_bid vs withdraw_bid). The descriptions further clarify edge cases like the difference between `get_offers` (bids) and `get_transfers` (completed transfers). There's no ambiguity between tools.
Naming follows a consistent snake_case pattern: get_* for read operations and verb_noun for mutations (place_bid, withdraw_bid, set_lineup). The verb-object ordering is uniform across all tools, making the API predictable and easy to navigate.
At 18–19 tools, the surface is broad but each tool maps to a distinct, legitimate fantasy-manager action (view squad, bid, list, lineup, news). The count is on the high side but every tool earns its place; nothing feels redundant.
Core read/write coverage is strong: every state (account, squad, market, offers, transfers, standings, news, watchlist) has a reader and every user action (bid, list, price, lineup, accept, watch) has a mutator. Minor gaps: watchlist can be added to but not removed, and there is no way to decline an incoming offer.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only ESPN, Sleeper, and Fantrax fantasy leagues for Claude, ChatGPT, and other AI tools.
Football fixtures, standings, and odds intelligence for AI agents.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Manage fitness coaching clients, workouts, programs, chats and funnels from your assistant.
