Send LinkedIn voice note

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

Annotations already mark destructiveHint=true, but the description goes far beyond: it warns that a real message 'cannot be unsent', clarifies it is sent from the user's own LinkedIn account, explains dry_run behavior, and notes external prerequisites (Chrome extension, LinkedIn sign-in). This materially adds destructive and environmental context above what annotations alone provide.

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 dense paragraph of about 160 words. Every sentence earns its place, especially the front-loaded warning about destructive real-world sending. It could benefit slightly from bullet formatting, but there is no fluff or repetition of schema content.

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 destructive send tool with 4 parameters, no output schema, and safety-critical preconditions, the description covers the full workflow: input selection (dry_run, recipient, one of two audio sources), environmental requirements, what is returned (message id), and how to follow up (get_send_status). Nothing an agent needs to call it correctly is left ambiguous.

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?

Even though schema coverage is 100%, the description adds critical meaning: it enforces 'exactly one' of audio_url or file_path (a constraint missing from the schema), identifies audio_url as coming from upload_audio, clarifies file_path must be uploaded first, and details recipient format ('LinkedIn profile URL (preferred), or just the name part after /in/'). This goes well beyond the schema's individual field descriptions.

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 specific verb and resource: 'Send a native LinkedIn voice note to a person via Svara.' It immediately distinguishes itself from siblings by referencing upload_audio (source of audio_url) and get_send_status (delivery check) within the same text. An agent can infer exactly what this tool does and how it differs from nearby tools without inspecting schemas.

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 gives explicit when-to-use guidance: only call with dry_run=false when 'the user has explicitly asked you to send this voice note to this recipient.' It also states dry_run defaults to true for validation, defines recipient eligibility ('someone the user can already message on LinkedIn'), and names required preconditions like the Svara Chrome extension and LinkedIn sign-in. This is thorough routing and guardrail guidance.

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