List discovery leads

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

With no annotations, the description carries the burden of disclosing behavior. It explicitly notes case-insensitive matching for company and status, and that query is a substring across all columns. This adds meaningful behavioral context beyond simply saying 'list'. It does not mention return format or that it is read-only, but the verb 'List' and source file imply a safe read operation.

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 sentences, front-loaded with the action and resource, then filters. Everything is relevant and no redundancy. It strikes an ideal balance between completeness and 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 simple list tool with three optional filters and no output schema, the description covers the source, filter behavior, and purpose. It omits return shape/pagination, but for a list operation on a spreadsheet this is minor and the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that all filters are optional, that company and query are substring matches (case-insensitive), and that status is an exact match. This supplements the schema's per-property descriptions with matching semantics.

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

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

The description clearly states the verb 'List' and the specific resource 'job leads from the discovery sheet (Job_Search_Discovery.xlsx)', which differentiates it from sibling tools like list_jobs that operate on other data. It also names the optional filters, making the tool's scope unambiguous.

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

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

The description clearly indicates the tool is for listing discovery leads from a specific file, implying use when discovery sheet data is needed rather than tracker jobs. It does not explicitly name alternatives or exclusions, but the resource specificity gives clear context for when to use this tool.

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