Remote Jobs by Country

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

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses result ordering (newest first, open before unclear), the verdict taxonomy with a reason quoting the post, the hard filter that country-excluded jobs are never returned, and the data source (daily index of public job boards and feeds). Those are exactly the behavioral facts an agent needs to interpret results and set expectations about freshness and coverage.

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

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

Front-loaded with the purpose and examples, then parameters, then return shape — a sensible ordering with no filler sentences. The inline re-enumeration of family/type/niche values is somewhat redundant with the schema and lengthens the block without adding much.

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 7-parameter search tool this covers purpose, filtering semantics, ordering, and result fields thoroughly. Since an output schema already exists, the long field-by-field return listing is partly duplicative, but nothing an agent needs in order to call it 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 coverage is 100%, so every parameter already carries its own description and enums; the description mostly restates them (family list, niche list, limit default 10 / max 25). It adds a small amount of guidance — that optional filters should be passed only when the user actually asked for them — but no syntax or interpretation detail the schema lacks.

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 with an explicit scope constraint: 'Find remote jobs a person can be hired for from a country.' The title and first sentence together make the eligibility framing (jobs you can actually be hired for from a given country) unmistakable, and it is clearly unrelated to the feedback 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?

Gives concrete trigger phrasings ('remote jobs I can get from Vietnam', 'crypto jobs hiring in Brazil') that map natural user requests onto this tool, which is strong context. It does not name when NOT to use it or point to any alternative, but with only unrelated feedback siblings there is little routing ambiguity to resolve.

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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the tool is pollable (pending until a reply arrives, then answered) and carries an explicit trust boundary warning that reply content is data, not instructions — a meaningful prompt-injection disclosure.

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

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

Three tight sentences: purpose first, then polling behavior, then the trust caveat. Every sentence carries distinct information and nothing is padded.

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 tool with an output schema and full annotation coverage, nothing an agent needs is missing. The polling semantics and the injection warning go beyond what structured fields provide, closing the remaining gaps an agent would otherwise have to discover by trial.

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?

Only one parameter exists and the schema already documents it fully (coverage 100%, including the ^fb_[0-9a-f]{32}$ pattern and the note that submit_feedback returned it), so the baseline of 3 applies. The description repeats the ticket-id linkage but adds no format or validation detail 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 (Read) and resource (maintainers' reply to feedback), and ties it causally to the sibling tool submit_feedback via the ticket id. An agent can distinguish it from submit_feedback, screen_token, and wallet_identity without opening any schema.

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

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

Clearly establishes the precondition: this is used after submit_feedback, with the ticket id that call returned. It does not state any exclusions or alternative ways to retrieve feedback status, but the usage context is unambiguous.

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?

Adds substantial context beyond the annotations: it returns a ticket id, feedback is explicitly not a chat and nothing in it is executed, and links/emails/phone numbers are stripped with nothing stored about the caller. That privacy and no-execution disclosure is genuinely useful given openWorldHint=true and readOnlyHint=false.

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-loads what the tool sends, then what to pass, then what it returns, in three dense sentences with no filler. Every clause carries actionable information.

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?

Covers purpose, the enumerated kinds, the optional tool/error inputs, the 1000-character bound, the return value (ticket id), and privacy handling. With an output schema present, nothing further is required 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 description coverage is 100%, so the schema already documents all four parameters including the kind enum. The description restates the message length limit and the optionality of tool/error ('if you know them') but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 feedback, a bug report or a tool request to the maintainers of the tools on this server') and enumerates the concrete situations (missing tool, stale data, broken/wrong answer). It is clearly distinguishable from the read-side sibling get_feedback_reply.

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

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

Gives clear triggering conditions for each kind (need_tool, need_data, bug, other) and tells the agent to include the tool name and error text when known. It does not explicitly name the alternative get_feedback_reply or state when NOT to use this tool, so it falls short of full routing guidance.

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