local_extract

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

With no annotations provided, the description carries the full burden. It discloses: local model usage, automatic routing based on input size, server-side file reading, JSON schema restriction with fallback, and return format. Minor gaps include error handling and behavior when both text and path are provided, but overall very transparent.

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 front-loaded with the crucial usage advice, then efficiently covers function, parameters, and technical details. Every sentence adds value, though a few technical details (size detection difference, schema auto) could be shortened without losing 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 the tool's complexity (3 params, no output schema initially? but actually has output schema which describes return), the description covers input alternatives, return format, automatic routing, and schema handling. It is sufficiently complete for an AI to select and invoke correctly, though edge cases like error states are omitted.

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%, so the description must compensate. It explains each parameter: fields ('keys of JSON'), text ('source text'), path ('file path, read server-side'). It clarifies they are alternatives but doesn't explicitly state mutual exclusivity or that one must be provided. Good but could be slightly clearer.

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 'extract' and the resource 'structured fields from text/file as JSON', and explicitly recommends it over Read for large files when only structured fields are needed. This distinguishes it from sibling tools like classify or summarize.

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 begins with a clear directive to prefer this tool over Read for files >200 lines or >10 KB when only structured fields are needed. It provides explicit context for when to use (large files, structured extraction) and implies when not to use (when literal content is needed, use Read).

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