Instagram Mobile MCP by Nova (CIVAI)

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

No annotations are provided, so the description carries the full disclosure burden, yet it only implies a read operation. It says nothing about authentication requirements, result volume, ordering, or whether the list is paginated, all of which matter for a listing 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?

Four words, front-loaded and free of waste, but also so terse that it borders on under-specification rather than disciplined brevity. Structure is fine; substance is thin.

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 is simple and the single parameter is fully documented, but with no output schema the description should at least sketch what a returned thread looks like or how results are bounded. As written, an agent cannot predict the response shape at all.

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% and the single optional parameter is documented there, so the baseline is 3. The description adds nothing about notification_message, which is a non-obvious fallback-message parameter for a listing operation that could use extra clarification.

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 (List) and resource (Direct inbox threads), which is enough to tell it apart from write-oriented siblings like send_dm and from single-thread tools like direct_thread. It never explicitly contrasts with direct_pending, however, leaving ambiguity about how 'inbox' relates to 'pending'.

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?

There is no statement of when to use this versus direct_pending or direct_thread, no prerequisites, and no indication of ordering, pagination, or result limits. The agent must infer everything about invocation context from the tool name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about whether this is a read-only operation, how results are ordered or paginated, or what permission or auth context is required. The odd notification_message parameter's failure-path behavior is also unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short, front-loaded sentence with zero filler. It is efficient, though its brevity leaves no room for the scoping or return-behavior detail an agent would want.

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 list tool with no annotations and no output schema, the description should explain what comes back (pending request objects, pagination, counts) and how it differs from inbox listing. None of that is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter at 100% schema coverage, the schema already fully documents notification_message, so baseline 3 applies. The description adds no meaning about why a listing tool takes a user-facing notification message.

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 ('List pending message requests'), which is clearly distinct from sending or reading threads. It does not, however, name or differentiate itself from the closest sibling, direct_inbox, which also lists conversations.

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?

There is no guidance on when to use this versus direct_inbox or direct_thread, and no mention of prerequisites or follow-up actions. The only hint of a use case comes from the adjective 'pending', leaving the agent to infer the rest.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only retrieval of recent media but says nothing about authorization, rate limits, result ordering, or pagination behavior.

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 short and front-loaded, but it is too terse for the tool's complexity. It reads more like an under-specified label than a structured explanation, so conciseness comes at the cost of clarity.

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 no annotations, no output schema, and a schema that lacks any hashtag parameter, the description is critically incomplete. It does not explain how the hashtag is specified or what the agent should expect from the call, leaving a major gap for a retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the sole parameter, notification_message, so the baseline is 3. The description adds no parameter meaning and notably does not explain how the hashtag itself is supplied, but the schema's own description covers the only declared 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 'Recent media for hashtag' largely restates the tool name rather than adding a clear verb or scope. It does not differentiate this tool from siblings such as user_feed or media_comments, so an agent gets only a minimal sense of what it retrieves.

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?

There is no guidance on when to use this tool, when not to use it, or which sibling tool is the alternative. The description gives no context about prerequisites, pagination, or appropriate use cases.

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

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

No annotations are provided, so the description carries the full behavioral burden and does not meet it. It says nothing about session persistence, whether credentials are stored, rate limiting, how a bad TOTP is surfaced, or what the tool returns on success or failure. For a stateful authentication operation with zero annotation coverage this is a significant disclosure gap.

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 compact sentences with the authentication purpose front-loaded and no filler. The Nova credential import reference is a slightly obscure aside, but it does carry format information, so it earns most of its space.

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 an authentication tool with no annotations and no output schema, the description should say what a successful vs failed login produces and how it relates to downstream calls. Neither is covered, leaving the agent unable to predict return values or prerequisite ordering. The 100% schema coverage offsets this only partially.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 and the schema already explains each field including the TOTP-vs-code distinction. The description adds only a small amount of value by giving the colon-delimited field order used for Nova credential import. It says nothing about the notification_message field or its fallback behavior.

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: authenticate into an Instagram Mobile account using username, password, and TOTP secret. It is unambiguous and no sibling tool overlaps with authentication. It stops short of a 5 only because it does not explicitly frame itself as the prerequisite gate for the other Instagram tools.

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?

There is no guidance on when this must be called relative to direct_inbox, user_feed, send_dm, or the rest of the sibling set. An agent gets no signal that this is a prerequisite step or what to do on a 2FA challenge or failed login. Usage is only implied by the tool name.

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

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

No annotations are provided, so the description carries the full burden, yet it says nothing about side effects, permissions, or irreversibility of posting a public comment. Most critically, it never explains how the target media post is identified, since the schema exposes only an optional notification_message and no post identifier.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short, front-loaded phrase with zero padding. It is efficiently sized, though the brevity edges into under-specification rather than true crispness.

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 mutation tool with no annotations and no output schema, the description leaves major gaps: how the target post is resolved, whether the comment is public, and what happens on success. None of that is recoverable from the schema, which only documents the fallback notification 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 description coverage is 100% and the single parameter's schema text is already rich (plain text only, used as fallback when a follow-up reply fails). The description adds nothing on top, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The phrase 'Comment on a media post' names a specific verb and resource, so the basic action is clear. However, it does nothing to differentiate this from the sibling 'media_comments' (likely a read of comments on the same resource), so an agent cannot tell the two apart from the text alone.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as media_comments or media_like. The agent must infer entirely on its own that this is the write counterpart to reading comments.

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

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

With no annotations, the description carries the full burden of disclosure and provides almost none: it does not say whether this is a read or a write, whether authentication or a media-id argument is required, whether results are paginated, or what a response looks like. The single clause only vaguely implies the tool operates on a media id.

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?

Five words is not conciseness but under-specification; there is no front-loaded purpose statement, no object, and no actionable content for the agent to act on.

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 annotations, no output schema, and an ambiguous verb, the description needs to establish read/write nature, scope, and return behavior. It supplies none of these, so an agent cannot call the tool correctly without guessing from the sibling names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the one parameter (notification_message) is fully documented in the schema, which sets the baseline at 3. The description adds nothing about parameters and notably does not explain why a notification message is the sole input for a comments operation, leaving a semantic mismatch unaddressed.

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?

"Comments on a media id" names a resource but the verb is ambiguous: it could mean "retrieve the comments for a media" or "post a comment on a media". Since a sibling named media_comment exists, an agent cannot tell which of the two handles reads vs. writes from this description alone.

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?

There is no guidance on when to use this tool versus media_comment, media_like, or the other media-related siblings. No prerequisites, no exclusions, no context of any kind.

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

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

No annotations are provided, so the description carries the full behavioral burden and does not meet it. It says nothing about whether the operation is idempotent when the post is already liked, whether it can be undone (unlike), what authentication or context identifies the target post, or what side effects (counts, notifications) occur.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no waste, front-loading the action. It is efficient, though the terseness borders on under-specification rather than disciplined brevity.

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 mutation tool with no annotations and no output schema, the definition is too thin. Most notably it never explains how the target media post is identified, since the only declared parameter is a fallback notification 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 description coverage is 100%, so the single parameter (notification_message) is fully documented in the schema and the baseline of 3 applies. The description adds no additional meaning about the parameter or about how the target post is specified.

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 verb (like) and resource (media post), which is unambiguous against siblings like media_comment. It does not, however, explicitly differentiate itself from adjacent read/comment tools or state the scope of the 'like' 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?

There is no guidance on when to use this versus media_comment or other media tools, and no prerequisites or exclusions are given. The agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the behavioral burden and does disclose the lookup transformation and prerequisite. However, it omits whether this is read-only, authentication/rate-limit needs, and what happens when the handle cannot be resolved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It communicates purpose and prerequisite immediately.

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 lookup with full schema coverage and no output schema, the description supplies the key ordering requirement and output type. Missing error behavior is a minor gap rather than a blocker.

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 both parameters are already documented in the input schema. The description adds no syntax, format, or optional-parameter guidance beyond the handle-to-id mapping.

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?

Uses a specific verb ('Resolve') and names the exact resource ('Instagram handle') and output ('internal user id'). The send_dm prerequisite further distinguishes it from sibling tools.

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

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

Explicitly states that it is required before send_dm, giving clear call ordering. It does not state when not to use it or whether it can be skipped when the internal id is already known.

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

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

No annotations are provided, so the description should carry the full behavioral burden. It does not disclose whether this is a read-only operation, what matching semantics apply, what results look like, or whether permissions are required.

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 a single front-loaded sentence with no wasted words. However, its brevity comes at the cost of important usage detail.

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 search tool with no annotations and no output schema, the description is too thin. It omits result behavior, query semantics, and any distinction from related tools like user_info.

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 implies a 'query' parameter that does not exist in the schema. The only actual parameter, notification_message, is completely unmentioned and seems unrelated to user search, which may confuse invocation.

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 gives a specific verb and resource: 'Search users'. It is clear what the tool does at a high level, but it does not distinguish it from sibling tools such as user_info, which may also retrieve user data.

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?

There is no guidance on when to use this search versus user_info or other user-related tools. It also does not state any prerequisites or expected query format.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not disclose whether the send can be undone, what permissions are required, whether rate limits apply, or what the result looks like; for a mutation tool this is a substantial gap.

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 a single front-loaded sentence with no wasted text. It prioritizes the action and the prerequisite dependency clearly.

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 messaging mutation tool with no annotations, no output schema, and no explicit error or permission behavior, the description is too thin. The schema covers parameters, but the description leaves important behavioral context unstated.

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 both parameters are already documented in the schema. The description only adds the recipient-resolution dependency and does not elaborate on the body text or notification_message semantics, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Send a Direct text message') and identifies the recipient resolution dependency. It is clear enough to distinguish from siblings like direct_thread or direct_inbox, though it does not explicitly contrast those alternatives.

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

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

The phrase 'the user resolved in resolve_recipient' implies a necessary prerequisite step, which is useful usage context. However, it gives no explicit when-not guidance, no alternatives for different DM operations, and no error or fallback conditions.

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

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

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about whether the call is a read, what scope of feed is returned, pagination, auth, or result shape. The single sentence adds no behavioral information at all.

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?

It is short, but brevity here is under-specification rather than economy: a three-word fragment with no verb, scope, or structure leaves the definition functionally empty.

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 annotations, no output schema, and a single unexplained parameter, the description would need to carry all context and instead provides none. Nothing an agent needs to invoke this correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, which sets a baseline of 3, but the only parameter (notification_message) is counterintuitive for an apparent feed-read tool and the description makes no attempt to explain it. A reader cannot infer whether the tool has side effects or why a user-facing fallback sentence is required.

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?

"User feed posts" only restates the tool name (user_feed) and never supplies a verb, so it is unclear whether it lists, searches, or creates feed posts. No differentiation from siblings such as user_stories, user_info, or hashtag_medias.

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?

There is no when-to-use guidance, no exclusion, and no named alternative among the many sibling read tools. An agent has no basis for choosing this over user_stories or hashtag_medias.

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

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

No annotations are provided, so the description carries the full disclosure burden and delivers almost nothing: no indication of read-only vs mutating behavior, no auth requirements, no mention of what a missing or private user returns. For an unnamed-behavior lookup tool this is a substantial gap.

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?

It is a single short sentence with no padding, so nothing is wasted, but that brevity comes from under-specification rather than efficiency. There is no front-loaded statement of the input contract or the result.

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 one parameter, no annotations, and no output schema, the description had a small job and still leaves the key mismatch (no user id parameter) unresolved. An agent cannot confidently construct a call from this.

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?

Coverage is nominally 100%, but the only parameter is notification_message (a follow-up failure message), which the description never mentions, while the description promises a 'user id' argument that does not exist in the schema. The description actively misdirects about the input contract.

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 identifies the resource (user profile info) and the lookup key (user id), which is more than a restatement of the name. However, it uses a noun phrase rather than a verb, gives no sense of scope or return shape, and does nothing to distinguish it from siblings like search_users or resolve_recipient.

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?

There is no guidance on when to use this versus search_users or resolve_recipient, both of which plausibly overlap. The phrase 'by user id' hints at a direct lookup, but the agent must infer the selection criteria entirely.

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

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

No annotations are provided, so the description carries the full burden and discloses nothing: not whether this is a read or write, not what "tray" means operationally, not the response shape or any auth/side-effect behavior.

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 words is technically concise but reflects under-specification rather than economy of expression. Nothing is front-loaded because there is nothing substantive to load.

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 one optional parameter, no output schema, and no annotations, the description still needs to say what the tool returns and roughly when to call it. Neither is present, leaving the agent unable to invoke this confidently despite the simple signature.

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 single parameter, notification_message, is documented in detail (plain text, no template syntax). The description adds nothing beyond the schema, but the baseline of 3 applies when the schema does the work.

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?

"User stories tray" is a bare noun phrase that essentially restates the tool name (user_stories); there is no verb indicating whether it fetches, lists, or renders stories. It gives no basis for distinguishing this from siblings like user_feed, user_info, or hashtag_medias.

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 contains no guidance on when to use this tool, when not to, or which sibling it replaces. An agent facing 13 related social-graph tools has nothing to route on.

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