Social media posts for small businesses from their own photos. Owner approves every post.
Scored across 12 tools
Each tool targets a distinct resource/action pair: approving a post, reading posts, reading brand, messaging the team, reading team replies, connecting an account, and listing accounts are all clearly separated. The three research tools (best_time_to_post, trending_audio, holiday_calendar) and the owner-specific ones (my_instagram_insights, my_social_accounts) are explicitly carved apart by negative guidance such as 'do not use it for a specific account's own best time.'
There is a mix of conventions: verb_noun (approve_post, connect_social_account, make_sample_posts, send_to_suara), get_ prefixed reads (get_my_brand, get_my_posts, get_suara_replies), a different 'my_' prefix for other reads (my_instagram_insights, my_social_accounts), and bare noun phrases (best_time_to_post, holiday_calendar, trending_audio). It is readable and semantically descriptive, but the read-only tools alone use three different naming patterns.
Twelve tools sit comfortably in the well-scoped range and each maps to a real step in the owner workflow (onboard, research, review, approve, message team, check replies). No tool looks like filler or a duplicate of another.
The lifecycle is largely covered: sample generation, brand/account reads, post review, approval/publishing, and a request channel with the human team. Remaining gaps are modest — there is no way to cancel or unschedule an approved post, no direct reject/revise action on a specific post (only indirectly via send_to_suara), and no disconnect-account operation, all of which agents can work around or escalate.
Use this only when the signed-in owner has clearly said to approve or post one specific post, after they've seen it. It schedules that post to be published on the owner's connected social accounts on its day (or right away if they say now). Publishing can't be undone from here. One post per call; it fails if the post isn't finished or no account is connected.
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | its_day (default): its planned day at their usual time. now: right away. | |
| postId | Yes | The post to approve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive and open-world, and the description adds valuable context: publishing cannot be undone from here, it schedules to connected accounts, and it fails if the post is unfinished or no account is connected. It also clarifies the owner-authorization prerequisite.
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 usage condition is front-loaded, followed by the effect, irreversibility, and operational limits. Every sentence carries useful information 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 two-parameter mutation with destructive and open-world annotations and no output schema, the description covers prerequisites, effect, irreversibility, and failure modes. It could still say more about what a successful call returns, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so postId and the when enum are already well documented. The description reinforces 'one specific post' and the now versus its_day behavior, but adds no syntax or meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: approving/posting one specific post, with the effect of scheduling it to connected social accounts. It does not explicitly differentiate itself from siblings such as get_my_posts or best_time_to_post, so it falls short of a 5.
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 an explicit usage gate: only when the signed-in owner has clearly said to approve or post one specific post after seeing it. It also states one-post-per-call and failure conditions, but does not name alternative tools for finding or preparing a post.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone asks when to post on Instagram, Facebook or TikTok in Kuala Lumpur, Penang, Johor Bahru, Singapore, Jakarta, Manila, Bangkok, New York, Los Angeles, Toronto, Vancouver, London, Sydney, Melbourne or Dubai (or one of those countries). Returns windows in that city's local time where two large 2026 studies (Sprout Social and Buffer) agree, shows where they disagree instead of picking one, and adds what we measured ourselves (restaurants and cafes in the Suara Restaurant Index, and Suara clients when there are enough posts). Do not use it for other cities, for a specific account's own best time, or to promise results.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City or country, e.g. Kuala Lumpur, KL, Toronto or Malaysia | |
| category | No | Kind of business, e.g. cafe or salon; optional | |
| platform | No | instagram, facebook or tiktok; optional (all three when left out) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (read-only, idempotent, non-destructive), and the description goes well beyond them: it discloses the data provenance (two 2026 studies plus Suara's own index and client data), that disagreements are surfaced rather than resolved, and that results are in the city's local time. That is exactly the behavioral context an agent needs to describe the answer honestly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the use case, then the return behavior, then the exclusions — a logical order. It is a single dense sentence-chain that's somewhat run-on, but each clause (cities, time zone, source agreement, own data, exclusions) carries information rather than 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?
There is no output schema, and the description fully compensates by explaining what comes back: local-time windows where two studies agree, explicit disagreement surfacing, and supplementary Suara measurements. Combined with the explicit exclusions, an agent has everything needed to call it and set expectations.
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 baseline is 3. The description still adds real value by closing the open-ended city parameter into an explicit supported set (plus accepting 'one of those countries'), which the schema only gestures at with 'e.g.' examples. It does not clarify how category interacts with the restaurant-index data source, which keeps it from a 5.
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?
Opens with a specific trigger verb plus resource ('when to post on Instagram, Facebook or TikTok') and enumerates the exact supported cities. No sibling tool (insights, posts, audio, holiday) overlaps with this function, so the agent can route on it immediately.
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 both sides explicitly: use it when someone asks about posting times in the listed geos, and 'Do not use it for other cities, for a specific account's own best time, or to promise results.' The exclusion of 'a specific account's own best time' implicitly points to per-account tools like my_instagram_insights.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the signed-in owner wants to connect their Instagram, Facebook Page or TikTok so approved posts can be published. Returns a secure link (valid for an hour) to the platform's own login page; Suara never sees their password. Instagram must be a Business or Creator account. Nothing is posted by connecting.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses important behavior: the tool returns a secure link valid for one hour, directs the user to the platform's own login page, and clarifies that Suara never sees the password. It also states that connecting posts nothing and flags the Instagram account-type requirement, all of which materially affect how an agent should use the tool.
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 concise sentences, front-loaded with the usage trigger and followed by the security/return-link behavior and constraints. Every sentence adds actionable information 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 one-parameter tool with no output schema, the description covers the trigger, supported platforms, return value (a short-lived secure link), security behavior, and a key prerequisite. Nothing essential for correct invocation 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 single parameter is fully constrained by an enum. The description compensates by enumerating the platforms and specifically clarifying 'Facebook Page' rather than personal Facebook, which adds meaning beyond the raw enum values. A 5 would require more detail about the enum's semantics or side effects.
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 ('connect their Instagram, Facebook Page or TikTok') and explains the downstream purpose (so approved posts can be published). It is clearly distinguishable from siblings like my_social_accounts, which presumably lists existing connections rather than initiating 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?
It gives a clear trigger condition: use when the signed-in owner wants to connect an account. It also scopes the supported platforms and notes the Instagram Business/Creator prerequisite. It does not explicitly name alternatives such as my_social_accounts, so it falls just 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.
Use this when the signed-in owner asks what Suara knows about their business or how their posts will sound. Returns their brand as Suara has it locked: name, voice, audience, colours, what they sell, and the notes they've given ("less pink", "never say cheap"). Read only. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read only. Changes nothing.' is partly repetition. What the description adds is genuinely useful: the data is the canonical 'locked' brand view, not a draft, plus the concrete contents of the payload including verbatim example notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger, then the return contents, then a safety line. The closing 'Read only. Changes nothing.' is two short sentences saying nearly the same thing and partly duplicates the annotations, a minor inefficiency in an otherwise tight 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?
There is no output schema, so the description carries the burden of describing the return value, and it does so concretely by enumerating the fields and giving example note strings. Nothing further is needed for an agent to call a zero-argument read tool 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?
The tool takes no parameters, so the baseline is 4. The description correctly says nothing about inputs and spends its words on what is returned 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?
States a specific resource (the brand record Suara holds) and its scope precisely: name, voice, audience, colours, offerings and stored notes. The phrase 'how their posts will sound' separates it from the sibling post-listing tools like get_my_posts or my_social_accounts.
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 a clear triggering condition ('when the signed-in owner asks what Suara knows about their business'). It does not name an alternative tool or an exclusion, but the use case is narrow enough that the trigger alone routes the agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the signed-in owner wants to see this week's posts, what's coming up, or what a post looks like. Returns each post's caption, hashtags, day and status (being made, ready to review, waiting for approval, scheduled, posted), shown in the Suara viewer with every slide. Give postId to see one post. Read only. Nothing is posted.
| Name | Required | Description | Default |
|---|---|---|---|
| images | No | Also attach the pictures to the answer (default false: the Suara viewer shows them) | |
| postId | No | Only this post (with every carousel slide) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint=false, yet the description reinforces safety ('Nothing is posted') and adds non-obvious behavior: the output renders in the Suara viewer rather than as raw data, and each post's status can be one of five enumerated states. It stops short of noting limits, ordering, or default date range.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the usage trigger, followed by return contents and the single-post shortcut; every sentence is functional. The parenthetical status list is long but earns its place by defining the vocabulary an agent will see in results.
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-value burden and does it: caption, hashtags, day, status, and viewer rendering. It leaves the actual date window ambiguous ('this week' vs. 'what's coming up') and says nothing about result volume or pagination.
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 already documented, including images and postId's carousel-slide nuance. The description only restates postId ('Give postId to see one post') and says nothing about the images flag or its default, 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 ('see this week's posts') plus the detail/answer shape, and 'Read only. Nothing is posted.' separates it from mutation siblings like approve_post and send_to_suara. It never names an alternative sibling explicitly, so it falls short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this when the signed-in owner wants to see this week's posts, what's coming up, or what a post looks like' gives clear trigger conditions and also signals the single-post mode via postId. No when-not-to-use conditions or named alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the signed-in owner asks if there's news from the Suara team, or after send_to_suara. Returns the team's replies and updates from the last few days (7 by default, up to 30): answers to their requests, posts ready to review, what was posted. Read only.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many days back (default 7, max 30) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it specifies the default lookback (7 days), the maximum (30 days), and the kinds of updates returned. It could say more about pagination or exact response shape, but with annotations present this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences. The usage trigger is front-loaded, followed immediately by what the tool returns, with no filler or redundant restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool with no output schema, the description covers when to call it, the default and maximum time window, and the nature of the returned content (answers, posts ready to review, what was posted). It stops short of detailing the exact response structure, but overall it gives enough context to invoke the tool 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 100%, and the only parameter ('days') is fully documented in the schema with its default and max. The description repeats the default and max but adds no new syntax, format, or edge-case guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and clearly identifies the resource: the Suara team's replies and updates. It distinguishes itself from the sibling send_to_suara by focusing on retrieving replies rather than sending requests, and it enumerates the content types returned.
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 triggering conditions: when the signed-in owner asks if there's news from Suara, or after send_to_suara. This clearly links it to a sibling tool, though it does not state when not to use it or name any other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone planning posts, promotions or opening hours needs the public holidays, state holidays or big shopping/observance days for Malaysia, Singapore, Indonesia, Philippines, Thailand, United States, Canada, United Kingdom, Australia or the UAE, for example 'when is Hari Raya this year' or 'holidays in Malaysia next month'. Returns dates verified against the official government list and a second independent calendar, which regions/states each one applies to, and lunar holidays that are expected but not yet confirmed (clearly marked). Do not use it for other countries, for school terms, or to invent dates it doesn't return.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date YYYY-MM-DD, optional (default a year from the start) | |
| from | No | Start date YYYY-MM-DD, optional (default today) | |
| country | Yes | Country name or 2-letter code, e.g. Malaysia or MY |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds real context beyond them: dates are cross-verified against an official government list and a second calendar, state/region applicability is included, and unconfirmed lunar holidays are marked. It doesn't discuss result size or paging, but the verification and confidence-marking behavior is the substantive disclosure 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?
Three sentences, front-loaded with the use case, then return behavior, then exclusions — a sensible ordering with no filler. The opening sentence is long and carries the country list plus two example queries, which is dense but each element 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?
There is no output schema, so the description carries the return-shape burden and does: dates, region/state applicability, and a confirmed-vs-expected distinction. Combined with annotations and a fully documented schema, an agent has everything needed to call this correctly and to know its limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds a capability the schema lacks: the enumerated list of ten supported countries, which matters because `country` has no enum and would otherwise be unbounded. The date-range semantics of from/to are only implied ('next month'), which is why this is not a 5.
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 (return public holidays / observance days) and names the exact user intents it serves ('when is Hari Raya this year', 'holidays in Malaysia next month'). Nothing among the sibling tools (posting, insights, accounts, audio) overlaps, so an agent can route cleanly.
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 explicit triggers ('planning posts, promotions or opening hours') plus concrete example queries, and then explicit exclusions: not for other countries, not for school terms, and not to invent dates. Both the when and the when-not are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone who owns or works for a small business wants to see what Suara would post for them. Give the business name plus its own website and/or up to 3 photos from the chat (not Instagram or delivery-app pages). Returns 3 designed posts with captions, full size, ready to use, made from the business's own photos and words; about a minute, so if it says they're still being made, call it again with the same business. Nothing is posted anywhere and no account is needed. One sample per person per day. Only for a business the user owns or works for.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Where the business is, optional | |
| photos | No | Up to 3 photos of the business uploaded in the chat | |
| website | No | The business's own website (https), optional if photos are given | |
| language | No | Language for the captions, optional (default: the business's own) | |
| business_name | Yes | The business's name | |
| what_to_promote | No | Something to feature in one post, optional (e.g. weekend brunch) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial context beyond them: nothing is posted and no account is needed, generation takes about a minute with a documented retry pattern ('call it again with the same business' if still being made), and a rate limit ('one sample per person per day'). This is exactly the operational detail 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?
Front-loaded with the when-to-use condition and packed with useful constraints; nearly every clause earns its place. The single dense run-on paragraph is slightly harder to scan than separated sentences, but there is 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 six-parameter generation tool with no output schema, the description covers the return value (3 designed posts with captions, full size), latency and retry behavior, rate limits, account requirements, and ownership restrictions. Nothing material is missing for an agent 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 the baseline is 3. The description adds real value by constraining input sources ('its own website and/or up to 3 photos from the chat (not Instagram or delivery-app pages)'), which clarifies valid values for the website and photos parameters beyond the schema text.
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 outcome ('Returns 3 designed posts with captions, full size, ready to use') for a specific audience (small business owners). It is clearly distinguishable from siblings like get_my_posts or approve_post, which retrieve or publish existing content rather than generating samples.
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?
Opens with an explicit trigger ('Use this when someone who owns or works for a small business wants to see what Suara would post for them') and adds exclusions ('Only for a business the user owns or works for', photos must come from chat, not Instagram or delivery-app pages). No inference needed to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the signed-in owner asks what to post, when to post, or how their Instagram is doing. Returns what's working on their own public Instagram: when they post, which posts do better, recurring themes. Read only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and the description's 'Read only' merely echoes that. It does add real context: the analysis is confined to the owner's own public Instagram, not competitors or private data. It says nothing about time windows, aggregation granularity, or what happens when the account has too little history.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the usage trigger front-loaded and the return contents immediately following. The closing 'Read only.' is redundant with the annotations and is the only slack.
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 zero parameters and no output schema, the description carries the return-value burden and does so by enumerating the three kinds of insight produced. An agent has enough to call it confidently and to describe the result to a user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters, so there is nothing for the description to disambiguate — baseline 4. The description correctly implies the scope is fixed to the signed-in owner rather than an account handle argument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (the owner's own public Instagram) and specific outputs (posting times, comparative post performance, recurring themes), which is far beyond the vague title. It does not, however, distinguish itself from close siblings like best_time_to_post or get_my_posts, which the agent could reasonably pick for the same questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this when the signed-in owner asks what to post, when to post, or how their Instagram is doing' gives a clear trigger and a clear subject (the signed-in owner). It stops short of exclusions — no statement about when to prefer best_time_to_post for timing or get_my_posts for raw post lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the signed-in owner asks which social accounts Suara can post to. Returns each connected platform and its username. Read only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds the return payload shape (platform plus username), which matters because there is no output schema. "Read only" restates the annotation rather than adding to it, keeping this below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the invocation trigger, then the return shape, then the safety note. No wasted text.
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?
A simple zero-parameter read tool with no output schema; the description supplies the trigger and the return contents, which is everything an agent needs 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?
The tool takes no parameters, so there is nothing for the description to document; the schema is trivially complete. Baseline 4 for a zero-parameter tool.
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: lists the social accounts the signed-in owner has connected. "Read only" implicitly separates it from the sibling connect_social_account, though no sibling is named explicitly.
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 a clear trigger condition: use when the signed-in owner asks which accounts Suara can post to. No explicit exclusion or routing to alternatives, but the trigger is specific enough that an agent can select it confidently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the signed-in owner has a request, idea or feedback for the Suara team who make their posts: what to post about, a promotion or event coming up, a change to a post (say which postId), a new look, more or fewer posts. Write the request clearly and completely in the owner's words. It sends a message to the team (nothing is posted or changed right away); the team replies later, so check with get_suara_replies.
| Name | Required | Description | Default |
|---|---|---|---|
| postId | No | The post it's about, if any | |
| message | Yes | What the owner wants, in full |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavior the annotations do not convey: nothing is posted or changed immediately, the team replies later, and the request should be written in the owner's words. Missing only operational details such as response shape or timing of replies.
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?
Description is front-loaded with the trigger, then the request categories, then the async behavior caveat. It is slightly list-heavy but every clause contributes a distinct usage signal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two simple params and no output schema, the description covers trigger, content guidance, side-effect behavior, and the follow-up tool. Only the expected return/immediate response is left implicit.
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 baseline is 3; the description still adds conditional meaning for postId ('a change to a post (say which postId)') and stresses that message should be complete and in the owner's own words.
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 (send a message to the Suara team) and enumerates the kinds of requests it covers, which cleanly separates it from post-manipulation siblings like approve_post or get_my_posts.
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?
Opens with an explicit trigger ('Use this when the signed-in owner has a request, idea or feedback...') and names the follow-up path ('check with get_suara_replies'), so the agent knows both when to call it and what to do next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when someone wants popular or trending songs to put on a Reel, TikTok or Story for a business in Malaysia, Singapore, Indonesia, Philippines, Thailand, United States, Canada, United Kingdom, Australia or the UAE, for example 'what songs are trending in Malaysia for Reels?'. Returns this week's songs charting on both Apple Music and Spotify in that country, with the trend (new, up, down) and whether a business account can use them. It is a music-chart signal, not a count of Reels or TikTok uses. Every song is marked business use 'unknown' with the platform's official rule: say so, and never tell a business a song is cleared. Not for picking royalty-free music or for countries outside the list.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many songs (default 10) | |
| country | Yes | Country name or 2-letter code, e.g. Malaysia or MY | |
| platform | No | Which app the post is for (changes the business-account rule shown). Default any. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses the data source (Apple Music + Spotify), the time window (this week), the trend vocabulary (new, up, down), and a critical operational caveat: business use is always 'unknown' and the agent must never tell a business a song is cleared. That is exactly the kind of behavioral constraint annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the use case, then return shape, then caveat, then exclusions — a logical order with no filler sentences. The long country enumeration and repeated caveat make it dense, but each clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still specifies the return contents (songs, trend direction, business-use marker) and the governing rule. All three parameters are covered, one required, and the tool's limits (country whitelist, unknown business-use) are fully stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real value the schema lacks: it enumerates the valid country set (which the schema only describes abstractly as 'country name or 2-letter code') and explains that platform changes the business-account rule shown, which is not stated in the platform enum's description.
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 (returns trending songs) and immediately scopes it: this week's Apple Music + Spotify charts for a given country, with trend and business-use flags. It also explicitly distinguishes itself from adjacent concepts ('a music-chart signal, not a count of Reels or TikTok uses') and from royalty-free music selection.
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 an explicit trigger ('when someone wants popular or trending songs to put on a Reel, TikTok or Story'), a concrete example query, the supported-country list, and two exclusions (not royalty-free music, not countries outside the list). An agent can decide to use or not use it without consulting anything else.
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.
approve_postbest_time_to_postconnect_social_accountget_my_brandget_my_postsget_suara_repliesholiday_calendarmake_sample_postsmy_instagram_insightsmy_social_accountssend_to_suaratrending_audioSocial posts and animated promo videos for small businesses, made and edited by chatting.
Social media for small businesses: write, illustrate, schedule and publish posts from your AI.
Photos and a brief in, finished social-media designs out. First design free, no account.
Runs your Instagram, Facebook, TikTok, YouTube and Google Business: posts, DMs, comments, reviews.
Add one secure layer between your agents and this server.