列出某公司所有職缺

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

With no annotations provided, the description carries the full disclosure burden, and it covers the critical non-obvious behaviors: complete pagination requires gear-value limits (20/50/100) held constant, non-gear limits silently truncate window tails with no backfill, pinned=true jobs only appear on page 1 without consuming limit quota, and total excludes pinned jobs. These are exactly the traps an agent cannot infer from schema.

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?

Purpose is front-loaded in the first sentence, followed by parameter sourcing, keyword usage, then pagination and pinned-job caveats. The text is dense but every clause earns its place — the ⚠️ warnings cover behaviors that would otherwise cause silent data loss or truncated 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?

For a 4-param tool with no annotations and no output schema, the description covers the returned fields, pagination semantics, keyword matching operators, pinned-job behavior, and parameter provenance from each sibling tool. Nothing an agent needs in order to invoke it correctly or interpret results 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 is already documented. The description adds value beyond the schema: the gear-value pagination rule, keyword matching scope (JD 內文含其他條件欄), the OR-not-AND semantics, and the provenance of companyUrlOrId from sibling tool outputs. Only slightly held back by the schema already carrying most parameter details.

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

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

The description opens with a precise verb+resource statement: listing a specific company's job openings on 104, with the returned fields enumerated (職稱、地區、薪資、學經歷要求、網址) and pagination noted. It also differentiates from the search_jobs sibling by positioning itself as the company-scoped tool for questions like 'does this company have C++'.

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?

Explicit when-to-use guidance is present: '某公司有沒有 C++' 這種問題用它, 別自己翻頁過濾職稱. It also instructs where to source companyUrlOrId from (find_company, search_jobs, get_job_detail) and warns about keyword OR semantics with the workaround (要 AND 請分次搜再交集). Alternatives and exclusions are stated rather than implied.

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